rubygems / guides

An effort to provide awesome documentation for the RubyGems ecosystem.

RubyGems Guides

An effort to provide awesome documentation for the RubyGems ecosystem.

Goals

• Be the definitive place for RubyGems knowledge
• Help out those new to RubyGems get started and get things done
• Make it easy to contribute more guides

Want to help?

If a guide is empty, start filling it out! Or, make a new one! Pull requests are gladly accepted!

• Pick one from the repo issues
• Port content from help.rubygems.org knowledge base
• Find lots of StackOverflow/ruby-talk questions and get their common answers in here
• Fill out more guides!

Setup

First, install the sass command line tool. On MacOS you can use Homebrew:

$ brew install sass/sass/sass

Then run bundle install and bundle exec rake. This will launch both Jekyll and Sass in "watch" mode.

The pages will be available at http://localhost:4000/

Every guide except for the Command and Specification Reference is just a straight up markdown page, so just go edit it!

For the Command Guide (command-reference.md), edit command-reference.erb and run:

$ bundle exec rake command_guide

For the Specification Guide, the documentation comes directly from the Gem::Specification class in RubyGems. Edit it, set your RUBYGEMS_DIR to where your code directory is, and run:

$ RUBYGEMS_DIR=~/Dev/ruby/rubygems bundle exec rake spec_guide --trace

Thanks

Huge thanks to thoughtbot whose playbook this is based off of.

Legal

The actual content of the articles is licensed under Creative Commons. The code that this project consists of is licensed under MIT.

guides's Issues

Improper escaping of command references.

Various > appear where > should be, most noticeable in:

gemlock rails-1.0.0 > lockdown.rb

... for an output redirect command.

http://guides.rubygems.org/command-reference/#gem_lock

Documentation about 'test_files' is confusing

According to the section in the guides that talks about test_files gemspec attribute, test_files is a collection of unit test file which will be loaded as unit tests when the user requests a gem to be unit tested. How does the user request a gem to be unit tested ? Looks like --test option was removed from the gem command. So how is this test_files gemspec attribute useful currently ?

Deploy guides with universal deploy script

Fix for #249 requires newer rdoc and installing newer rdoc is impossible on GitHub Pages, because it doesn't allow that. It is possible to just commit generated static site from Travis https://docs.travis-ci.com/user/deployment-v2/providers/pages/

required_rubygems_version not documented in guide

http://guides.rubygems.org/specification-reference/ does not mention required_rubygems_version, which has been around for a couple years now...

Outdated info in SSL Certificate Update

In reference to this page, RubyGems.org recently updated their SSL cert, and I find myself with a broken RubyGem. While running through the page for a fix, I found a couple of issues.

• In the Installing using update packages (NEW) section, it says to download the proper version of RubyGems for your installation, but the links to the 2.2.5 and 2.6.7 release tags do not have any .gem file in the release.
• I was already running RubyGems 2.2.5, and the latest RubyGems for 2.2.x is 2.2.5. The guide only mentions that I need to update to the latest 2.2.x, but what is there to update when its already the latest?
• In the Manual solution to SSL issue section, the link to the AddTrustExternalCARoot-2048.pem is broken. The RubyGems GitHub appears to have restructured the ssl_cert folder.
• While I did not test it out myself, several users report that updating directly to the latest RubyGems solves the issue. Could a description be written down?

A lot of links are referencing to this page, so I think its important to get it up to date.

Regards.

Gems with extensions: Gem layout: confusing content

The Gem layout section of the Gems with extensions page is quite confusing. So far I don't know enough about C extensions to improve the text myself, so I'm just opening an issue for it.

Some extensions will be partially written in C and partially written in ruby. If you are going to support multiple languages, such as C and Java extensions, you should put the C-specific ruby files under the ext/ directory as well in a lib/ directory.

What exactly does the portion highlighted by bold typeface mean? I'm also not sure if it is syntactically correct or not.

When the extension is built the files in ext/my_malloc/lib/ will be installed into the lib/ directory for you.

As a reader, I expect this paragraph, following immediately after an example directory listing, to refer to paths contained in the listing. But the listing does not include the directory ext/my_malloc/lib. I'm confused.

Document manual SSL workaround

As mentioned by @drbrain in my gist:

https://gist.github.com/luislavena/f064211759ee0f806c88

I think we should add this to guides.rubygems.org

How should I proceed to submit this new document? I'm not familiar with guides codebase to do that, so wanted to gather feedback first so I can submit a pull request.

Thank you.

Document default gems

Move original topic from @headius (a.k.a. @Headies):

There's currently docs/guides on how to use most aspects of RubyGems except for default gems. I recognize that default gems are largely used by implementers (and perhaps installers) but there should still be some guide or howto written up.

I'm willing to write it, if there's a good place for such articles to live.

cc rubygems/rubygems#662

Broken GemTesters link

On http://guides.rubygems.org/make-your-own-gem/#writing-tests, the "GemTesters" link is pointing to http://test.rubygems.org/ which seems to be dead or down at the moment

Review API documentation on guides.rubygems.org

Examining problems in Artifactory local repo for gems we discovered that bundle installs send wrong api calls to repository
If you execute bundle install the following wrong api cals are sent.

1. Get https://rubygems.org/versions with incorrect syntax and without gem name. The corect api call should be
   Get https://rubygems.org/api/v1/versions/rails.json
2. GET https://rubygems.org/api/v1/dependencies with incorrect syntax and without gem. The correct rest apo call should be:
   GET https://rubygems.org/api/v1/dependencies?gems=chef-vault
   below you will find artifactory apache log file with incorrect calls

10.151.80.71 - - [26/Feb/2019:08:45:15 +0100] "GET /artifactory/api/gems/rubygems/versions HTTP/1.1" 404 129 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:16 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies HTTP/1.1" 200 - "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:16 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=chef-vault HTTP/1.1" 200 3420 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:16 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=chef HTTP/1.1" 200 358751 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:16 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=addressable%2Cbundler%2Cbunny%2Cchef-config%2Cchef-zero%2Cdiff-lcs%2Cerubis%2Cffi%2Cffi-yajl%2Chighline%2Ciniparse%2Ciso8601%2Cjson%2Cmime-types%2Cmixlib-archive%2Cmixlib-authentication%2Cmixlib-cli%2Cmixlib-config%2Cmixlib-log%2Cmixlib-shellout%2Cnet-sftp%2Cnet-ssh%2Cnet-ssh-multi%2Cohai%2Cplist%2Cproxifier%2Cpry%2Crest-client%2Crspec-core%2Crspec-expectations%2Crspec-mocks%2Crspec_junit_formatter%2Cserverspec%2Cspecinfra%2Csyslog-logger%2Cuuidtools%2Cwin32-api%2Cwin32-certstore%2Cwin32-dir%2Cwin32-event%2Cwin32-eventlog%2Cwin32-mmap%2Cwin32-mutex%2Cwin32-process%2Cwin32-service%2Cwin32-taskscheduler%2Cwindows-api%2Cwindows-pr%2Cwmi-lite%2Cyajl-ruby HTTP/1.1" 200 406822 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:16 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=amqp%2Cextlib%2Cmoneta%2Cpuma%2Crdp-ruby-wmi%2Cruby-hmac%2Cruby-openid%2Cstomp%2Csystemu%2Ctreetop HTTP/1.1" 200 33745 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:16 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=abstract%2Camq-protocol%2Carchive-tar-minitar%2Cbcrypt_pbkdf%2Cbones%2Cbuilder%2Ccoderay%2Cechoe%2Cfuzzyurl%2Chashie%2Choe%2Chttp-accept%2Chttp-cookie%2Cipaddress%2Cjruby-pageant%2Claunchy%2Clibyajl2%2Cmethod_source%2Cmime-types-data%2Cmulti_json%2Cneedle%2Cnet-dhcp%2Cnet-scp%2Cnet-ssh-gateway%2Cnet-telnet%2Cnetrc%2Cnokogiri%2Cptools%2Cpublic_suffix%2Crack%2Crake%2Crbnacl%2Crbnacl-libsodium%2Crcov%2Crdoc%2Crspec%2Crspec-its%2Crspec-support%2Cruby_parser%2Csfl%2Cslop%2Csolve%2Cspoon%2Ctermios%2Ctest-unit%2Cthin%2Ctomlrb%2Cwin32-ipc%2Cwin32console%2Cyard HTTP/1.1" 200 156684 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:17 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=amq-client%2Cenglish%2Ceventmachine%2Cfacets%2Cffi-win32-extensions%2Cpolyglot%2Cruby-yadis%2Cstructured_warnings HTTP/1.1" 200 21917 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:17 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=ParseTree%2CRubyInline%2Callison%2Cbones-extras%2Cbones-git%2Ccamping%2Cconfiguration%2Ccucumber%2Cdaemons%2Cdep_selector%2Cdomain_name%2Ceventmachine-le%2Cfcgi%2Cgemcutter%2Chttp_parser.rb%2Clanguage%2Clittle-plugger%2Cloquacious%2Cmemcache-client%2Cmini_portile%2Cmini_portile2%2Cminitar%2Cminitar-cli%2Cminitest%2Cmolinillo%2Cmongrel%2Cpcap%2Cpkg-config%2Cpower_assert%2Cpreforker%2Cracc%2Crake-compiler%2Crexical%2Crubyforge%2Csemverse%2Csexp_processor%2Cspicycode-rcov%2Csqlite3%2Csyntax%2Ctenderlove-frex%2Ctest-spec%2Cweakling%2Cwin32-file HTTP/1.1" 200 98731 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:17 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=SexpProcessor%2CZenTest%2Cactiverecord%2Cactivesupport%2Cbones-rcov%2Cbones-rspec%2Cbones-rubyforge%2Cbones-zentest%2Ccgi_multipart_eof_fix%2Ccucumber-core%2Ccucumber-expressions%2Ccucumber-formatter-dots%2Ccucumber-wire%2Cdep-selector-libgecode%2Cevent-bus%2Cfastthread%2Cflexmock%2Cgem_plugin%2Cgherkin%2Cgherkin3%2Cgit%2Cjson_pure%2Cmab%2Cmarkaby%2Cmetaid%2Cmocha%2Cmulti_test%2Cpattern-match%2Cpowerbar%2Cterm-ansicolor%2Cunf%2Cwin32-file-stat HTTP/1.1" 200 183851 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:17 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=activemodel%2Cactiverecord-deprecated_finders%2Cansi%2Carel%2Cbackports%2Cc21e%2Cconcurrent-ruby%2Ccucumber-messages%2Ccucumber-tag_expressions%2Ci18n%2Cmetaclass%2Cos%2Cspruz%2Cthread_safe%2Ctins%2Ctrollop%2Ctzinfo%2Cunf_ext%2Czeitwerk HTTP/1.1" 200 73439 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:17 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=atomic%2Cbcrypt-ruby%2Ccurses%2Cfunctional-ruby%2Cgoogle-protobuf%2Cref HTTP/1.1" 200 19545 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:17 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=bcrypt HTTP/1.1" 200 1921 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"
10.151.80.71 - - [26/Feb/2019:08:45:18 +0100] "GET /artifactory/api/gems/rubygems/api/v1/dependencies?gems=bundler HTTP/1.1" 200 14018 "-" "bundler/1.16.1 rubygems/2.7.6 ruby/2.5.1 (x86_64-pc-linux-gnu) command/install options/no_install,wro2096v.centrala.bzwbk 0861e96b13b2dd66"

Unable to locate the malloc method in the extension source code.

The extconf.rb file looks for methods called "malloc" and "free"

abort 'missing malloc()' unless have_func 'malloc'
abort 'missing free()' unless have_func 'free'

Searching the code, it is easy to see where free is defined to Ruby:

rb_define_method(cMyMalloc, "free", my_malloc_release, 0);

I have been unable to locate any trace of the malloc method. What am I missing here?

zero width spaces between consecutive hyphens in docs

https://guides.rubygems.org/command-reference/#gem-environment

Like this: -​-config-file.

Makes searching for -- on the page impossible.

(https://help.github.com/en/articles/transferring-an-issue-to-another-repository)

Broken link in Guide make-your-own-gem

In guides/make-your-own-gem.md
"of
tutorials" link is broken
it moved to https://github.com/seattlerb/minitest/blob/master/README.rdoc

Match nav hover styles to rubygems.org

Wrong attribute group in the gemspec reference

specification-reference.md lists authors= (and author=) as optional, but it is required.

$ gem build without_author.gemspec
WARNING:  See http://guides.rubygems.org/specification-reference/ for help
ERROR:  While executing gem ... (Gem::InvalidSpecificationException)
authors may not be empty

GEM BUILD is not correct in command reference on web (even with RubyGems 3.2.19)

Even after the fix rubygems/rubygems#4613 (and subsequent d7db87d), we are seeing something wrong at https://guides.rubygems.org/command-reference/:

as is

Expected

A guide to security vulnerabilities and best practices

It would be really useful to have a guide to indicate best practices for

a) Users of gems who spot security vulnerabilities on how to report issues and...

b) ...gem maintainers on how to distribute information about new releases they have made to their gems to fix security vulnerabilities.

RubyGems/Bundler guides cross-linking.

Generally, people use Bundler to create gems. While http://guides.rubygems.org/make-your-own-gem/ is still useful to have (so people can understand what exactly it's doing), should it have a note pointing people to https://bundler.io/v1.13/guides/creating_gem.html for most cases?

test/unit vs. minitest in the Make your own gem page

I was following the Make your own gem tutorial (which was awesome!), and I got stuck on the testing part.

After some research, I got it working by making these changes in the test/test_hola.rb:

Change require 'test/unit' to require 'minitest/autorun'
Change Test::Unit::TestCase to MiniTest::Unit::TestCase

I was using Ruby version 2.1.2, and I assume this has something to do with differing Ruby Versions.

I am not sure if or how this information should be included in the tutorial, but just wanted to start a conversation about it and see what you think.

Thanks for the great tutorial!

Fix up the spec reference source

The Specification Reference source specification-reference.md is riddled with HTML tags. If I had to guess I'd say that it used to be a generated HTML doc that got semi-converted to Markdown.

Things that can/should have the HTML stripped out of them:

• Plain HTML that would be auto-generated by Markdown (e.g. <p>, <pre>, etc.)
• Formatted multi-line code samples such as the example Gemfile at the top of the guide
• HTML encoded characters

Things that should be left alone:

• The empty page section anchors

404 error accessing the Specification Reference page

The Specification Reference page (e.g. guides.rubygems.org → Specification Reference) appears to be missing:

404

File not found

The site configured at this address does not contain the requested file.

If this is your site, make sure that the filename case matches the URL.
For root URLs (like http://example.com/) you must provide an index.html file.

Read the full documentation for more information about using GitHub Pages.

I've tried various variations in various browsers e.g.:

• http://guides.rubygems.org/specification-reference
• http://guides.rubygems.org/specification-reference/
• https://guides.rubygems.org/specification-reference
• https://guides.rubygems.org/specification-reference/

["Rakefile"] are not files

on http://guides.rubygems.org/make-your-own-gem/

% gem build thegem.gemspec
ERROR:  While executing gem ... (Gem::InvalidSpecificationException)
    ["Rakefile"] are not files
% gem -v
1.8.5
% ruby -v
ruby 1.9.2p180 (2011-02-18 revision 30909) [x86_64-darwin10.7.0]

next links are circular

http://guides.rubygems.org/specification-reference/ 's next link points to:

http://guides.rubygems.org/command-reference whose next link points back to specification-reference.

Add page on gem command extensions

It'd be useful to collect things like 'gem man' and 'gem open' for those who want to get more out of their gems.

Proposed supplement to (or overhaul of) the "Make Your Own Gem" tutorial

I originally mis-filed this issue under the rubygems/rubygems.org repo (#1597), and am migrating it here for further discussion.

In short, I think there are two important improvements that could be made to the official guide, and would like to know if the maintainers would be open to incorporating a modified version of the alternative guide I wrote on my blog.

1. Discuss what's going on under the hood of the RubyGems system.

Newcomers to programming would benefit from a guided introduction to the habit of tinkering with a system to see why things work the way they do and how a change in one place produces a change in another. For example, the guide briefly covers the creation and purpose of a gemspec, but it totally misses the opportunity to examine the gemspec from an established project and use that as a way to discuss convention (like specifying a gem's version number in a lib/<gem_name>/version.rb file). The line below is as close as it comes:

The gemspec defines what’s in the gem, who made it, and the version of the gem. It’s also your interface to RubyGems.org. All of the information you see on a gem page (like jekyll’s) comes from the gemspec.

Note that there is no mention of where to find jekyll's gemspec, and no excerpt of its source.

Without a discussion of what a .gem file is made of and what you can do with it, it's nearly impossible to deviate from the steps prescribed in the guide. In the end, RubyGems still feels like incomprehensible magic, which does not empower readers to go out and build something of their own.

2. Address the distinction between building a library and publishing a gem.

Building and publishing a library can mark a budding programmer's first steps into a software community of any kind. When I was setting out to build my first gem, I did not yet understand how things were supposed to fit together or what the conventions and best practices were. The official guide does touch on all the important bits — splitting code into multiple files, creating binaries, testing your code, writing documentation, etc. — but each one is given a very short treatment, where most really deserve a book's worth of elaboration. When I read it, I came away with the impression that tests, documentation, and code organization were tasks to be completed, rather than subjects to understand or skills to develop.

Given that the guide is written as a step-by-step tutorial, this quick flyover conflates the vast complexity of software development with minutiae of software packaging. The bits about building a library deserve to be extracted into a separate guide, with each section containing links to resources for where to learn more.

Enable HTTPS for guides.rubygems.org

GitHub Pages can do HTTPS for custom domains now. Woo!

This means that we can finally have https://guides.rubygems.org/ -- double woo!

Steps to make the magic happen:

1. Update the DNS CNAME entry for guides.rubygems.org to be rubygems.github.io (may not be necessary, but would be good to do, as per GitHub documentation).
2. Go to https://github.com/rubygems/guides/settings and remove the contents of "Custom domain" box. Click Save.
3. Enter guides.rubygems.org back into "Custom domain" box. Click Save.
4. Wait up to one hour for SSL certificate to be generated.
5. Click "Enforce HTTPS" checkbox.

Once that's done, can start updating other places to reference the HTTPS version of the guides site.

Minimum `gem` command version for MFA support?

https://guides.rubygems.org/using-mfa-in-command-line/
I enabled MFA on my rubygems account, tried "UI and API" level but it failed without prompting me for OTP. I didn't run gem push directly but via gem-release (svenfuchs/gem-release#88), but apparently the problem was simply that my gem command was too old.
I got it via rbenv install 2.5.6; gem --version said 2.7.6.2, and it doesn't support --otp, so I guess doesn't know how to prompt either.
Building ruby 2.6.4 gave me gem 3.0.3 which does support --otp so I guess would Just Work (will confirm next time I release a version).

Anyway, it wasn't obvious from the error message that's my problem. It'd be nice to update the MFA guide with minumum required version of gem and/or minimum version of Ruby it comes with.

Cleaning up "SSL Certificate Updates" posts

Hi! I'm currently editing the SSL Certificate Updates post to make it a bit clearer (my changes).

Is there any actual need for the Manual Solution To SSL Issue section? As far as I can tell, you should be able to use the Installing Using Update Packages section in all cases. Is that not correct?

Rebuild command-reference for RubyGems 3.0.2

3.0.2 was released on 2019-01-01: https://github.com/rubygems/rubygems/releases/tag/v3.0.2

`files` examples in specification reference have extra spaces

I was reading the examples for the files field in the specification reference and was confused by the extra spaces:

guides/specification-reference.md

Lines 136 to 146 in 751b95c

	<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;rake&#39;</span>
	<span class="ruby-identifier">spec</span>.<span class="ruby-identifier">files</span> = <span class="ruby-constant">FileList</span>[<span class="ruby-string">&#39;lib .rb&#39;</span>,
	<span class="ruby-string">&#39;bin/*&#39;</span>,
	<span class="ruby-string">&#39;[A-Z]*&#39;</span>,
	<span class="ruby-string">&#39;test/ *&#39;</span>].<span class="ruby-identifier">to_a</span>
	<span class="ruby-comment"># or without Rake...</span>
	<span class="ruby-identifier">spec</span>.<span class="ruby-identifier">files</span> = <span class="ruby-constant">Dir</span>[<span class="ruby-string">&#39;lib/ *.rb&#39;</span>] <span class="ruby-operator">+</span> <span class="ruby-constant">Dir</span>[<span class="ruby-string">&#39;bin/*&#39;</span>]
	<span class="ruby-identifier">spec</span>.<span class="ruby-identifier">files</span> <span class="ruby-operator">+=</span> <span class="ruby-constant">Dir</span>[<span class="ruby-string">&#39;[A-Z]*&#39;</span>] <span class="ruby-operator">+</span> <span class="ruby-constant">Dir</span>[<span class="ruby-string">&#39;test/**/*&#39;</span>]
	<span class="ruby-identifier">spec</span>.<span class="ruby-identifier">files</span>.<span class="ruby-identifier">reject!</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">fn</span><span class="ruby-operator">|</span> <span class="ruby-identifier">fn</span>.<span class="ruby-identifier">include?</span> <span class="ruby-string">&quot;CVS&quot;</span> }
	</pre>

Rendered:

require 'rake' 
 spec.files = FileList['lib     .rb', 
                       'bin/*', 
                       '[A-Z]*', 
                       'test/   *'].to_a 
  
 # or without Rake... 
 spec.files = Dir['lib/   *.rb'] + Dir['bin/*'] 
 spec.files += Dir['[A-Z]*'] + Dir['test/**/*'] 
 spec.files.reject! { |fn| fn.include? "CVS" } 
 

These spaces were already present before and removed in 19948c7, but introduced back again in 2ca58b0.

The spaces are an issue themselves, but the fact that this issue was already fixed in the past and then regressed due to a rebuild suggests that it should be fixed somewhere else too in order to fix it once and for all.

It's stunning!

Love the new rubygems site its stunning! Keep up!

command-reference.md - 'Options' parsing - CommonMark issue

I noticed this when I needed to reference:

https://msp-greg.github.io/ruby_trunk/rubygems/file.command-reference.html

I'm using the same md parser as GitHub (commonmarker), while rdoc uses it's own md parser. Not sure about Jekyll...

Anyway, check the options sections in:
https://github.com/rubygems/guides/blob/gh-pages/command-reference.md
vs:
https://github.com/MSP-Greg/guides/blob/md-commonmark/command-reference.md

The following line:

guides/Rakefile

Line 129 in 9bf5801

options += "* #{helpline}\n"

Changed to:

options += "* #{helpline.strip}\n"

fixes the issue.

404s

http://guides.rubygems.org/specification-reference/

First two links are 404s.

Do we publish rubygems rdoc somewhere on rubygems.org ? I'm trying to find a sanctioned place to link to and can't find one.

Some characters are replaced with spaces in Gem::Specification#files document

https://guides.rubygems.org/specification-reference/#files

The example code is the following

require 'rake'
spec.files = FileList['lib     .rb',
                      'bin/*',
                      '[A-Z]*',
                      'test/   *'].to_a

# or without Rake...
spec.files = Dir['lib/   *.rb'] + Dir['bin/*']
spec.files += Dir['[A-Z]*'] + Dir['test/**/*']
spec.files.reject! { |fn| fn.include? "CVS" }

But it looks incorrect. 'lib .rb' is strange. It should be 'lib/**/*.rb'.
https://github.com/rubygems/rubygems/blob/778b7440d78f06bebdaef3cb67f4ab7f97635f51/lib/rubygems/specification.rb#L241-L252

Guide does not explain how `description` should be formatted.

The Guide does not explain how the description should be formatted.

The rubygems specification says you could/should include your whole README in the description field:

Notes

As of Rubygems 1.3.2 there is no longer any automatic formatting of the description. Versions prior to this reformatted the description into a single line.

The description should be more detailed than the summary. You might consider copying all or part of your project’s README into this field.

But the rubygems.org specification doesn't say anything about how the description is formatted.

There are some examples out there, such as the net-ldap gem which imply that no formatting happens and the description field is just mashed into a single line.

What's the correct way to format a description and what should go into it?

Merge RubyGems Guides and Bundler Website Guides

I also noticed that I couldn't search on in RubyGems Guides while it possible on Bundler website. Hope that's a feature we gain.

Gem Best Practices and or Template

The guide here is good but doesn't cover many other issues such as code organization (nicely written about here). Either way, and as beneficial guides can be, I think lack of a base/template gem and a metric tool might be a factor in explaining the extraordinary variability in quality seen when randomly looking at a gem source code.

Not sure why this topic isn't well covered since it's important to for an ecosystem to be built upon healthy components!

credentials configuration for publishing gems

I guess this is more rubygems-the-website related, but, a colleague of mine reported trouble finding docs on how to configure his credentials to publish gems. Indeed, the only place I see this discussed is when I go to edit my profile.

I would like to see this information be more accessible.

Document reverse_dependencies endpoints

From rubygems/rubygems.org#123, we need to get docs up for the reverse_dependencies endpoints.

Remove references to `-rubygems`.

https://guides.rubygems.org/faqs/ mentions ruby -rubygems a few times. The -rubygems part should be removed, since it's deprecated.

SSL guide is incomplete

The SSL guide appears to only work if you're not using a version manager for Ruby (RVM, rbenv, etc).

I'm still collecting information about and helping resolve this in rubygems/rubygems#1758.

However, some relevant links from that thread:

• https://railsapps.github.io/openssl-certificate-verify-failed.html
• https://gist.github.com/fnichol/867550
• https://rvm.io/support/fixing-broken-ssl-certificates

EDIT: The gist has insecure instructions.

Dead/broken link on the /security page

The first link in the General section points to http://rubygems.rubyforge.org/rubygems-update/Gem/Security.html, which is inaccessible. The link has been updated in 2013, I guess it’s time to update it again.

DNS seems to be messed up somehow.

I can't access guides.rubygems.org.

Use different gem version on command line

Hello. I have installed rails 3.2.17, 4.0.4. When I call rails on command line it will use 4.0.4. I want to call 3.2.17 and find the answer in Stackoverflow:

$ rails _3.2.17_ new app

Is there any document on this feature? Thanks!

Specification Reference - Files has erroneous whitespace in examples

There are some whitespace issues in the examples provided on http://guides.rubygems.org/specification-reference/#files. For example:

require 'rake'
spec.files = FileList['lib     .rb',
                      'bin/*',
                      '[A-Z]*',
                      'test/   *'].to_a

# or without Rake...
spec.files = Dir['lib/   *.rb'] + Dir['bin/*']
spec.files += Dir['[A-Z]*'] + Dir['test/**/*']
spec.files.reject! { |fn| fn.include? "CVS" }

Update overview of how plugins work to reflect improvement in plugin system

The plug in system was reworked in rubygems/rubygems#3108 to make it faster by caching plugins from gems into a central location instead of having to find and load them from each time 🎉 ✨

In a discussion on an plugin related issue, it was discovered that the current overview in the documentation does not reflect how things work after the updates to the plugin system.

The current language says:

As of RubyGems 1.3.2, RubyGems will load plugins installed in gems or $LOAD_PATH. Plugins must be named 'rubygems_plugin' (.rb, .so, etc) and placed at the root of your gem's #require_path. Plugins are discovered via Gem::find_files then loaded.

But this is no longer true, because it does not use find_files anymore. Instead, plugins are saved to a plugins directory from which they can be loaded (instead of having to load and evaluate all gemspecs from gems in a search for plugins they might contain).

We can update the language used in the overview to match a similar change of language in that PR here: https://github.com/rubygems/rubygems/blob/a28724fdd9262d716e6facb1950387a0a6ac4c73/lib/rubygems.rb#L45-L48

I'll attach a PR to this issue containing those proposed changes.

Document single-digit pessimistic versions

As discussed in rubygems/rubygems#1684, while there is API documentation around single-digit pessimistic versions, there is no mention of this behavior or expectation in the guide at http://guides.rubygems.org/patterns/#pessimistic-version-constraint. We should explain!

Specification Reference 'required gemspec attributes' not correct

The docs seem to be wrong here. ( http://guides.rubygems.org/specification-reference/ ) I.e., platform, require_paths, and rubygems_version all have default values and are not required in a gemspec file.

The example gemspec file at the top of that page does not include these attributes.

REQUIRED GEMSPEC ATTRIBUTES

author=
authors=
files
name
platform=
require_paths=
rubygems_version
summary
version

Cannot build "spec_guide", the jekdoc template seems incomplete.

I am trying to build the docs so I can contribute (remove or fix broken links #27), but I cannot build the spec_guide.

I have installed jekyll (and run it once to build any required pages), and have the Rubygems source and rdoc installed.

However, rake spec_guide is missing a jekdoc template file. Not sure what to do now.

Parsing sources...
100% [ 1/ 1]  ../rubygems/lib/rubygems/specification.rb                         

Generating Darkfish format into /Users/testuser/Source/guides/html...
rake aborted!
error generating Gem.html: No such file or directory - /Users/testuser/Source/guides/rdoc/generator/template/jekdoc/_head.rhtml (Errno::ENOENT)

Tasks: TOP => spec_guide => rdoc_spec => html/index.html
(See full trace by running task with --trace)

Misalignment in gem install on Command Reference

https://guides.rubygems.org/command-reference/#gem-install

We are seeing as follows:

• -​-minimal-deps - Don’t upgrade any dependencies that already meet version requirements
• 　
  • -​-[no-]post-install-message Print post install message
• -g, -​-file [FILE] - Read from a gem dependencies API file and install the listed gems

because there are two spaces between option string and description for --[no-]post-install-message:

$ docker run --rm ruby:2.6 gem install --help | head -50 | tail -5
        --minimal-deps               Don't upgrade any dependencies that already
                                     meet version requirements
        --[no-]post-install-message  Print post install message
    -g, --file [FILE]                Read from a gem dependencies API file and
                                     install the listed gems