Cleaning up the readme to be clearer, more useful, easier to read #859

Closed
wants to merge 4 commits into
from

Conversation

Projects
None yet
2 participants

Cleaning up the readme to be clearer, provide more useful links, and generally flow better. The file extension will have to be changed to .md or .markdown as a result of the formatting.

I noticed the README was slightly lacking and hadn't been updated in a while so I figured my first commit should be something I'm good at: Writing.

Obviously there are 2 pieces missing, however: Versions, sub-header "Latest" and "1.2". Since Rubinius is currently 1.2.3, as per the website, I figured more details about new crap should be written about there.

While the summary details file extension changing, it looks pretty good in plain tet.

Kurtis Rainbolt-Greene Cleaning up the readme to be clearer, provide more useful links, and …
…generally flow better.


I noticed the README was slightly lacking and hadn't been updated in a while so I figured my first commit should be something I'm good at: Writing.

Obviously there are 2 pieces missing, however: Versions, sub-header "Latest" and "1.2". Since Rubinius is currently 1.2.3, as per the website, I figured more details about new crap should be written about there.
7edf06d
Owner

brixen commented May 6, 2011

Thanks for working on this Kurtis. Here's some feedback:

  1. While it sounds fun and enthusiastic, I think changing "What is Rubinius" to "Rubinius: Ruby Harder" could actually interfere with helping people understand the project. The README should be rather conservative with language, using simple, direct terms. Although, that heading might make a great blog post.
  2. I'm not a fan of READMEs in Markdown format. While Markdown is certainly clean, stuff like word is really ugly. Furthermore, github's formatting of styled READMEs is really terrible at the moment. Also, the fixed line length formatting should be retained, even if we do switch to Markdown. I'd much rather keep the README very simple and concise and point folks to the website for more docs. The website is embedded in the source so whether or not they have internet access, they have access to it. (In other words, if they have the README, they have the docs)
  3. I'd prefer to have only the latest information in the README. There's no real use for previous version's information when installing this version.

While it sounds fun and enthusiastic, I think changing "What is Rubinius" to "Rubinius: Ruby Harder" could actually interfere with helping people understand the project.

While I think "interfere" is a strong descriptor, I agree none-the-less.

While Markdown is certainly clean, stuff like word is really ugly.

Use of the bold can be taken out, but generally the plain text version is just as good in that it reads easier than a list of 4 ordered points (the original).

Also, the fixed line length formatting should be retained, even if we do switch to Markdown.

I loath to have that, as it makes adding, editing, and maintaining the documentation that much more annoying. As it exists in this pull request each sentence has its own line. Makes it easier to add, remove, and update any line (as well as other things). Any time you need an editor utility (format to column 80 type stuff) to "fix" your documentation files...

I'd prefer to have only the latest information in the README. There's no real use for previous version's information when installing this version.

Makes sense, I only added the "previous version" sub-headers as the original was labeled 1.1. Taking the Version section out all together would be a better idea.

Owner

brixen commented May 6, 2011

Well, it takes one command in Vim and most editors I've used to reformat the selection. The fixed line length ensures that the text is readable without scrolling left if the pager does not wrap lines or if the column width is large. Even if the pager wraps, reading something with many varied lengths is not pleasant.

I think that it's interesting what github does with rendering the README on the project page, but it's not a substitute for a good website with docs and the rendering of it shouldn't override the original use of the READM, a brief text document that orients you in a project.

So, I'm going to strongly urge that the README stay text with fixed width lines.

Agreed. In lieu of that I'm going to see if I can't get Github to make the READMEs render at a smaller width.

brixen closed this May 8, 2011

Owner

brixen commented May 8, 2011

Thanks again for working on this, Kurtis.

After reviewing your proposed changes, I'm going to reject this pull request. I'll explain my reasons below. If I fail to address any of your changes, let me know.

I will be reviewing the README in light of some of your changes and we can certainly discuss issues you may have. Let's discuss them directly, rather than with a patch.

  1. One of the main changes reorganizes the order of presentation in the README. Generally, information should be presented in the order of most important, next most important, etc. I have chosen the existing order in the README for this reason. The first information is a concise summary of Rubinius in plain english. The second is the LICENSE. The third is installing, etc. I don't consider your ordering of information to be as useful.
  2. The plain text nature of the README favors simple english text. Consequently, the existing
    1. What is Rubinius

reads much better and is more simple than

Rubinius
======

The use of = for underlining is not necessary and adds a lot more visual clutter than a simple numbering of headings.

  1. Breaking out features of Rubinius into bullet points does not offer anything over a natural english enumeration.
  2. Embedding commands with delimiters in the text actually makes them less clear than setting them off in their own line like the existing README has them.
  3. Use of link syntax like "[LICENSE](https://github.com/evanphx/rubinius/blob/master/LICENSE\)" is unnecessary. If the user is browsing on github, the LICENSE file is right above the README rendering. If they are looking in the source directory, the LICENSE file is right alongside the README. Consequently, just referring to the LICENSE file is simple, plain english that provides all the necessary information.
  4. The existing enumeration of Goals in bullet points uses plain english sentences. There is no need to 1. set off the sentences in bullets, which is already a means of emphasis, and also 2. add a summary word to the beginning. That breaks the reading flow and doesn't offer additional information.

Again, I'll review the existing README for clarity and correctness of information. What I strive to achieve with the README is the essential information about Rubinius presented in simple, plain english text with pointers to more specific information.

I'm not sure how I can respond as each item seems to be a preference of style and opinion rather than reasoned points. I can't argue, or debate, a person's opinion. The changes I made were based on readability, flow of information, and brevity of which I have experience with as a technical writer and designer.

I can't even fathom the world where an english list is equal to or easier than bulleted list, much less explain why anchored links in a document are a good idea. On the web.

I will concede that a lot of my changes were made specifically for the rendered view, but that's what Ruby repositories do. Either with Markdown, Textile, or RDoc a majority of popular Ruby public repositories render their READMEs. While we both agree that the Github styling is off I don't think throwing the baby out with the bathwater is quite necessary. Rendered READMEs are still loads easier to read on the web than plaintext.

With that said, I certainly don't need to make a readme file into a battle hill. I tried to commit to an open source project, it was considered, and discussed. I'm willing to claim that as a reasonable enough success.

Owner

brixen commented May 8, 2011

I may be reading too much into your comments but I dislike what I perceive to be your casting this as a battle of wills over opinion.

I'm sure you do have experience as a technical writer and designer. But let's assume that I do as well. Appeal to authority is a logic error. So rather than that, let's discuss the principles I am applying.

The simplest way to convey information is through a plain english sentence. Additional structure adds emphasis and should be used sparingly. This is simply good writing style emphasize in Strunk & White and many times before and after. It's also consistent with Tufte's principle of least effective difference. In the opening sentence, we could have these forms:

This project includes this, that, and those.

This project includes: 1) this, 2) that, and 3) those.

This project includes:

  • this
  • that
  • those

Each of those may be appropriate depending on the context and the information presented. I do use a bulleted enumeration later in the README where appropriate (i.e. where the information is longer and no easily read in a single sentence).

The use of the bulleted enumeration in the opening sentence is not justified based on the brevity of the information. That is my opinion based on application of those principles to a likely first-time reader. Many people that I talk to about Rubinius, and many of them quite capable developers, don't necessarily understand those concepts. A simple english enumeration gives all the information. That doesn't guarantee it will be understood. But adding emphasis to words that may already not be understood does not thereby magically trigger understanding.

The issue of whether the README should be formatted for github is probably the central disagreement. The fact that github renders the README file is interesting but not dispositive. I'm not willing to accept that the primary use of the README is github's landing page. At CodeConf, there were a number of criticisms of the project landing page design. So, I'm unconcerned with whether other projects are using formatted READMEs (appeal to the crowd is also a logic error), but rather whether the README conveys information in all the contexts it may be read.

Again, we appreciate your contribution of time and ideas to this. There are lots of areas to help out. I would consider your contribution a success as well. What's something else you'd be interested in learning about or hacking on in Rubinius?

@brixen brixen added a commit that referenced this pull request Jun 16, 2014

@brixen brixen Updated RubyGems to 2.3.0.
RubyGems 2.3.0 installed

=== 2.3.0 / 2014-06-10

Minor enhancements:

* Added the `open` command which allows you to inspect the source of a gem
  using your editor.
  Issue #789 by Mike Perham. Pull request #804 by Vitali F.
* The `update` command shows a summary of which gems were and were not
  updated.  Issue #544 by Mark D. Blackwell.
  Pull request #777 by Tejas Bubane.
* Improved "could not find 'gem'" error reporting.  Pull request #913 by
  Richard Schneeman.
* Gem.use_gemdeps now accepts an argument specifying the path of the gem
  dependencies file.  When the file is not found an ArgumentError is raised.
* Writing a .lock file for a gem dependencies file is now controlled by the
  --[no-]lock option.  Pull reuqest #774 by Jeremy Evans.
* Suggestion of alternate names and spelling corrections during install can be
  suppressed with the --no-suggestions option.  Issue #867 by Jimmy Cuadra.
* Added mswin64 support.  Pull request #881 by U. Nakamura.
* A gem is installable from an IO again (as in RubyGems 1.8.x and older).
  Pull request #716 by Xavier Shay.
* RubyGems no longer attempts to build extensions during activation.  Instead
  a warning is issued instructing you to run `gem pristine` which will build
  the extensions for the current platform.  Issue #796 by dunric.
* Added Gem::UserInteraction#verbose which prints when the --verbose option is
  given.  Pull request #811 by Aaron Patterson.
* RubyGems can now fetch gems from private repositories using S3.  Pull
  request #856 by Brian Palmer.
* Added Gem::ConflictError subclass of Gem::LoadError so you can distinguish
  conflicts from other problems.  Pull request #841 by Aaron Patterson.
* Cleaned up unneeded load_yaml bootstrapping in Rakefile.  Pull request #815
  by Zachary Scott.
* Improved performance of conflict resolution.  Pull request #842 by Aaron
  Patterson.
* Add documentation of "~> 0" to Gem::Version.  Issue #896 by Aaron Suggs.
* Added CONTRIBUTING file.  Pull request #849 by Mark Turner.
* Allow use of bindir in windows_stub_script in .bat
  Pull request #818 by @unak and @nobu
* Use native File::PATH_SEPARATOR and remove $ before gem env on
  Gem::Dependency#to_specs. Pull request #915 by @parkr
* RubyGems recommends SPDX IDs for licenses now.  Pull request #917 by
  Benjamin Fleischer.

Bug fixes:

* RubyGems now only fetches the latest specs to find misspellings which speeds
  up gem suggestions.  Pull request #808 by Aaron Patterson.
* The given .gem is installed again when multiple versions of the same gem
  exist in the current directory.  Bug #875 by Prem Sichanugrist.
* Local gems are preferred by name over remote gems again.  Bug #834 by
  jonforums.
* RubyGems can install local prerelease gems again.  Pull request #866 by
  Aaron Patterson.  Issue #813 by André Arko.
* RubyGems installs development dependencies correctly again.  Issue #893 by
  Jens Wille.
* RubyGems only installs prerelease versions when they are requested again.
  Issue #853 by Seth Vargo, special thanks to Zachary Scott and Ben Moss.
  Issue #884 by Nathaniel Bibler.
* Fixed RubyGems list and search command help.  Pull request #905 and #928 by
  Gabriel Gilder.
* The list of gems to uninstall is always sorted now.  Bug #918 by postmodern.
* The update command only updates exactly matching gem names now.  Bug #919 by
  postmodern.
* Gem::Server now supports prerelease versions.  Bug #857 by Marcelo Alvim.
* RubyGems no longer raises an exception immediately when gems are missing
  with RUBYGEMS_GEMDEPS.  A warning is printed instead.  Issue #886 by Michael
  Kaiser-Nyman.
* Commands using the rubygems.org API no longer try to sign-in when a
  non-rubygems API key has been chosen.  Bug #826 by Ben Sedat.
* Updated documentation of Gem::Specification#executables to indicate that
  only ruby scripts are allowed.  Bug #830 by Geoff Nixon.
* Gem dependency API supports multiple platforms for #platform and #platforms
  now.  Bug #821 by johnny5-.
* Gem dependency API supports lockfiles without explicit sources.  Bug #820 by
  johnny5-.
* Gem dependency API supports lockfiles with multiple sources.  Bug #822 by
  johnny5-, bug #851 by sumit shah.
* Gem dependency API supports lockfiles with git sources using branch, tag and
  ref.  Bug #822 by johnny5-, #931 by Christoph Blank.
* Gem dependency API no longer raises an exception when a gem does not exist
  in one of the configured sources.  Bug #897 by Michael Kaiser-Nyman.
* Gem dependency API no longer lists development dependencies in the lockfile.
  Bug #768 by Diego Viola, #916 by Santiago Pastorino.
* SSL configuration entries in ~/.gemrc are properly round-tripped.  Bug #837
  by Noah Luck Easterly.
* The environment command now shows the system configuration directory where
  the all-users gemrc lives.  Bug #827 by Ben Langfeld.
* Improved speed of conflict checking when activating gems.  Pull request #843
  by Aaron Patterson.
* Improved speed of levenshtein distance for gem suggestion misspellings.
  Pull requests #809, #812 by Aaron Patterson.
* Restored persistent connections.  Pull request #869 by Aaron Patterson.
* Reduced requests when fetching gems with the bundler API.  Pull request #773
  by Charlie Somerville.
* Reduced dependency prefetching to improve install speed.  Pull requests
  #871, #872 by Matthew Draper.
* RubyGems now avoids net/http auto-proxy detection.  Issue #824 by HINOHARA
  Hiroshi.
* Removed conversion of Gem::List (used for debugging installs) to unless
  necessary.  Pull request #870 by Aaron Patterson.
* RubyGems now prints release notes from the current release.  Bug #814 by
  André Arko.
* RubyGems allows installation of unsigned gems again with -P MediumSecurity
  and lower.  Bug #859 by Justin S. Collins.
* Fixed typo in Jim Weirich's name.  Ruby pull request #577 by Mo Khan.
* Fixed typo in Gem.datadir documentation.  Pull request #868 by Patrick
  Jones.
* Fixed File.exists? warnings.  Pull request #829 by SHIBATA Hiroshi.
* Fixed show_release_notes test for LANG=C.  Issue #862 by Luis Lavena.
* Fixed Gem::Package from IO tests on windows.  Patch from issue #861 by Luis
  Lavena.
* Check for nil extensions as BasicSpecification does not initialize them.
  Pull request #882 by André Arko.
* Fixed Gem::BasicSpecification#require_paths receives a String for
  @require_paths. Pull requrest #904 by @danielpclark
* Fixed circular require warnings.  Bug #908 by Zachary Scott.
* Gem::Specification#require_paths can no longer accidentally be an Array.
  Pull requests #904, #909 by Daniel P. Clark.
* Don't build extensions if `build_dir/extensions` isn't writable.
  Pull request #912 by @dunric
* Gem::BasicSpecification#require_paths respects default_ext_dir_for now.  Bug
  #852 by Vít Ondruch.

=== 2.2.2 / 2014-02-05

Bug fixes:

* Fixed ruby tests when BASERUBY is not set.  Patch for #778 by Nobuyoshi
  Nakada.
* Removed double requests in RemoteFetcher#cache_update_path to improve remote
  install speed.  Pull request #772 by Charlie Somerville.
* The mkmf.log is now placed next to gem_make.out when building extensions.
* `gem install -g --local` no longer accesses the network.  Bug #776 by Jeremy
  Evans.
* RubyGems now correctly handles URL passwords with encoded characters.  Pull
  request #781 by Brian Fletcher.
* RubyGems now correctly escapes URL characters.  Pull request #788 by Brian
  Fletcher.
* RubyGems can now unpack tar files where the type flag is not given.  Pull
  request #790 by Cody Russell.
* Typo corrections.  Pull request ruby/ruby#506 by windwiny.
* RubyGems now uses both the default certificates and ssl_ca_cert instead of
  one or the other.  Pull request #795 by zebardy.
* RubyGems can now use the bundler API against hosted gem servers in a
  directory.  Pull request #801 by Brian Fletcher.
* RubyGems bin stubs now ignore non-versions.  This allows RubyGems bin stubs
  to list file names like "_foo_".  Issue #799 by Postmodern.
* Restored behavior of Gem::Version::new when subclassed.  Issue #805 by
  Sergio Rubio.

------------------------------------------------------------------------------
f29994f

@brixen brixen added a commit that referenced this pull request Jun 16, 2014

@brixen brixen Updated RubyGems to 2.3.0.
RubyGems 2.3.0 installed

=== 2.3.0 / 2014-06-10

Minor enhancements:

* Added the `open` command which allows you to inspect the source of a gem
  using your editor.
  Issue #789 by Mike Perham. Pull request #804 by Vitali F.
* The `update` command shows a summary of which gems were and were not
  updated.  Issue #544 by Mark D. Blackwell.
  Pull request #777 by Tejas Bubane.
* Improved "could not find 'gem'" error reporting.  Pull request #913 by
  Richard Schneeman.
* Gem.use_gemdeps now accepts an argument specifying the path of the gem
  dependencies file.  When the file is not found an ArgumentError is raised.
* Writing a .lock file for a gem dependencies file is now controlled by the
  --[no-]lock option.  Pull reuqest #774 by Jeremy Evans.
* Suggestion of alternate names and spelling corrections during install can be
  suppressed with the --no-suggestions option.  Issue #867 by Jimmy Cuadra.
* Added mswin64 support.  Pull request #881 by U. Nakamura.
* A gem is installable from an IO again (as in RubyGems 1.8.x and older).
  Pull request #716 by Xavier Shay.
* RubyGems no longer attempts to build extensions during activation.  Instead
  a warning is issued instructing you to run `gem pristine` which will build
  the extensions for the current platform.  Issue #796 by dunric.
* Added Gem::UserInteraction#verbose which prints when the --verbose option is
  given.  Pull request #811 by Aaron Patterson.
* RubyGems can now fetch gems from private repositories using S3.  Pull
  request #856 by Brian Palmer.
* Added Gem::ConflictError subclass of Gem::LoadError so you can distinguish
  conflicts from other problems.  Pull request #841 by Aaron Patterson.
* Cleaned up unneeded load_yaml bootstrapping in Rakefile.  Pull request #815
  by Zachary Scott.
* Improved performance of conflict resolution.  Pull request #842 by Aaron
  Patterson.
* Add documentation of "~> 0" to Gem::Version.  Issue #896 by Aaron Suggs.
* Added CONTRIBUTING file.  Pull request #849 by Mark Turner.
* Allow use of bindir in windows_stub_script in .bat
  Pull request #818 by @unak and @nobu
* Use native File::PATH_SEPARATOR and remove $ before gem env on
  Gem::Dependency#to_specs. Pull request #915 by @parkr
* RubyGems recommends SPDX IDs for licenses now.  Pull request #917 by
  Benjamin Fleischer.

Bug fixes:

* RubyGems now only fetches the latest specs to find misspellings which speeds
  up gem suggestions.  Pull request #808 by Aaron Patterson.
* The given .gem is installed again when multiple versions of the same gem
  exist in the current directory.  Bug #875 by Prem Sichanugrist.
* Local gems are preferred by name over remote gems again.  Bug #834 by
  jonforums.
* RubyGems can install local prerelease gems again.  Pull request #866 by
  Aaron Patterson.  Issue #813 by André Arko.
* RubyGems installs development dependencies correctly again.  Issue #893 by
  Jens Wille.
* RubyGems only installs prerelease versions when they are requested again.
  Issue #853 by Seth Vargo, special thanks to Zachary Scott and Ben Moss.
  Issue #884 by Nathaniel Bibler.
* Fixed RubyGems list and search command help.  Pull request #905 and #928 by
  Gabriel Gilder.
* The list of gems to uninstall is always sorted now.  Bug #918 by postmodern.
* The update command only updates exactly matching gem names now.  Bug #919 by
  postmodern.
* Gem::Server now supports prerelease versions.  Bug #857 by Marcelo Alvim.
* RubyGems no longer raises an exception immediately when gems are missing
  with RUBYGEMS_GEMDEPS.  A warning is printed instead.  Issue #886 by Michael
  Kaiser-Nyman.
* Commands using the rubygems.org API no longer try to sign-in when a
  non-rubygems API key has been chosen.  Bug #826 by Ben Sedat.
* Updated documentation of Gem::Specification#executables to indicate that
  only ruby scripts are allowed.  Bug #830 by Geoff Nixon.
* Gem dependency API supports multiple platforms for #platform and #platforms
  now.  Bug #821 by johnny5-.
* Gem dependency API supports lockfiles without explicit sources.  Bug #820 by
  johnny5-.
* Gem dependency API supports lockfiles with multiple sources.  Bug #822 by
  johnny5-, bug #851 by sumit shah.
* Gem dependency API supports lockfiles with git sources using branch, tag and
  ref.  Bug #822 by johnny5-, #931 by Christoph Blank.
* Gem dependency API no longer raises an exception when a gem does not exist
  in one of the configured sources.  Bug #897 by Michael Kaiser-Nyman.
* Gem dependency API no longer lists development dependencies in the lockfile.
  Bug #768 by Diego Viola, #916 by Santiago Pastorino.
* SSL configuration entries in ~/.gemrc are properly round-tripped.  Bug #837
  by Noah Luck Easterly.
* The environment command now shows the system configuration directory where
  the all-users gemrc lives.  Bug #827 by Ben Langfeld.
* Improved speed of conflict checking when activating gems.  Pull request #843
  by Aaron Patterson.
* Improved speed of levenshtein distance for gem suggestion misspellings.
  Pull requests #809, #812 by Aaron Patterson.
* Restored persistent connections.  Pull request #869 by Aaron Patterson.
* Reduced requests when fetching gems with the bundler API.  Pull request #773
  by Charlie Somerville.
* Reduced dependency prefetching to improve install speed.  Pull requests
  #871, #872 by Matthew Draper.
* RubyGems now avoids net/http auto-proxy detection.  Issue #824 by HINOHARA
  Hiroshi.
* Removed conversion of Gem::List (used for debugging installs) to unless
  necessary.  Pull request #870 by Aaron Patterson.
* RubyGems now prints release notes from the current release.  Bug #814 by
  André Arko.
* RubyGems allows installation of unsigned gems again with -P MediumSecurity
  and lower.  Bug #859 by Justin S. Collins.
* Fixed typo in Jim Weirich's name.  Ruby pull request #577 by Mo Khan.
* Fixed typo in Gem.datadir documentation.  Pull request #868 by Patrick
  Jones.
* Fixed File.exists? warnings.  Pull request #829 by SHIBATA Hiroshi.
* Fixed show_release_notes test for LANG=C.  Issue #862 by Luis Lavena.
* Fixed Gem::Package from IO tests on windows.  Patch from issue #861 by Luis
  Lavena.
* Check for nil extensions as BasicSpecification does not initialize them.
  Pull request #882 by André Arko.
* Fixed Gem::BasicSpecification#require_paths receives a String for
  @require_paths. Pull requrest #904 by @danielpclark
* Fixed circular require warnings.  Bug #908 by Zachary Scott.
* Gem::Specification#require_paths can no longer accidentally be an Array.
  Pull requests #904, #909 by Daniel P. Clark.
* Don't build extensions if `build_dir/extensions` isn't writable.
  Pull request #912 by @dunric
* Gem::BasicSpecification#require_paths respects default_ext_dir_for now.  Bug
  #852 by Vít Ondruch.

------------------------------------------------------------------------------

RubyGems installed the following executables:
  /source/rubinius/rbx/bin/gem

RubyGems system software updated
d4ab0c3

@brixen brixen added a commit that referenced this pull request Oct 21, 2014

@brixen brixen Updated RubyGems to 2.4.2.
Installing RubyGems 2.4.2
RubyGems 2.4.2 installed

=== 2.4.2 / 2014-10-01

This release was sponsored by Ruby Central.

Bug fixes:

* RubyGems now correctly matches wildcard no_proxy hosts.  Issue #997 by
  voelzemo.
* Added support for missing git_source method in the gem dependencies API.
* Fixed handling of git gems with an alternate install directory.
* Lockfiles will no longer be truncated upon resolution errors.
* Fixed messaging for `gem owner -a`.  Issue #1004 by Aaron Patterson, Ryan
  Davis.
* Removed meaningless ensure.  Pull request #1003 by gogotanaka.
* Improved wording of --source option help.  Pull request #989 by Jason Clark.
* Empty build_info files are now ignored.  Issue #903 by Adan Alvarado.
* Gem::Installer ignores dependency checks when installing development
  dependencies.  Issue #994 by Jens Willie.
* `gem update` now continues after dependency errors.  Issue #993 by aaronchi.
* RubyGems no longer warns about semantic version dependencies for the 0.x
  range.  Issue #987 by Jeff Felchner, pull request #1006 by Hsing-Hui Hsu.
* Added minimal lock to allow multithread installation of gems.  Issue #982
  and pull request #1005 by Yorick Peterse
* RubyGems now considers prerelease dependencies as it did in earlier versions
  when --prerelease is given.  Issue #990 by Jeremy Tryba.
* Updated capitalization in README.  Issue #1010 by Ben Bodenmiller.
* Fixed activating gems from a Gemfile for default gems.  Issue #991 by khoan.
* Fixed windows stub script generation for Cygwin.  Issue #1000 by Brett
  DiFrischia.
* Allow gem bindir and ruby.exe to live in separate diretories.  Pull request
  #942 by Ian Flynn.
* Fixed handling of gemspec in gem dependencies files to match Bundler
  behavior.  Issue #1020 by Michal Papis.
* Fixed `gem update` when updating to prereleases.  Issue #1028 by Santiago
  Pastorino.
* RubyGems now fails immediately when a git reference cannot be found instead
  of spewing git errors.  Issue #1031 by Michal Papis

=== 2.4.1 / 2014-07-17

Bug fixes:

* RubyGems can now be updated on Ruby implementations that do not support
  vendordir in RbConfig::CONFIG.  Issue #974 by net1957.

=== 2.4.0 / 2014-07-16

Minor enhancements:

* The contents command now supports a --show-install-dir option that shows
  only the directory the gem is installed in.  Feature request #966 by Akinori
  MUSHA.
* Added a --build-root option to the install command for packagers.  Pull
  request #965 by Marcus Rückert.
* Added vendor gem support to RubyGems.  Package managers may now install gems
  in Gem.vendor_dir with the --vendor option to gem install.  Issue #943 by
  Marcus Rückert.

Bug fixes:

* Kernel#gem now respects the prerelease flag when activating gems.
  Previously this behavior was undefined which could lead to bugs when a
  prerelease version was unintentionally activated.  Bug #938 by Joe Ferris.
* RubyGems now prefers gems from git over installed gems.  This allows gems
  from git to override an installed gem with the same name and version.  Bug
  #944 by Thomas Kriechbaumer.
* Fixed handling of git gems in a lockfile with unversioned dependencies.  Bug
  #940 by Michael Kaiser-Nyman.
* The ruby directive in a gem dependencies file is ignored when installing.
  Bug #941 by Michael Kaiser-Nyman.
* Added open to list of builtin commands (`gem open` now works).  Reported by
  Espen Antonsen.
* `gem open` now works with command-line editors.  Pull request #962 by Tim
  Pope.
* `gem install -g` now respects `--conservative`.  Pull request #950 by Jeremy
  Evans.
* RubyGems releases announcements now now include checksums.  Bug #939 by
  Alexander E. Fischer.
* RubyGems now expands ~ in $PATH when checking if installed executables will
  be runnable.  Pull request #945 by Alex Talker.
* Fixed `gem install -g --explain`.  Issue #947 by Luis Lavena.  Patch by
  Hsing-Hui Hsu.
* RubyGems locks less during gem activation.  Pull request #951 by Aaron
  Patterson and Justin Searls, #969 by Jeremy Tryba.
* Kernel#gem is now thread-safe.  Pull request #967 by Aaron Patterson.
* RubyGems now handles spaces in directory names for some parts of extension
  building.  Pull request #949 by Tristan Hill.
* RubyGems no longer defines an empty Date class.  Pull Request #948 by Benoit
  Daloze.
* RubyGems respects --document options for `gem update` again.  Bug 946 by
  jonforums.  Patch by Hsing-Hui Hsu.
* RubyGems generates documentation again with --ignore-dependencies.  Bug #961
  by Pulfer.
* RubyGems can install extensions across partitions now.  Pull request #970 by
  Michael Scherer.
* `-s` is now short for `--source` which resolves an ambiguity with
  --no-suggestions.  Pull request #955 by Alexander Kahn.
* Added extra test for ~> for 0.0.X versions.  Pull request #958 by Mark
  Lorenz.
* Fixed typo in gem updated help.  Pull request #952 by Per Modin.
* Clarified that the gem description should not be excessively long.  Part of
  bug #956 by Renier Morales.
* Hid documentation of outdated test_files related methods in Specification.
  Guides issue #90 by Emil Soman.
* RubyGems now falls back to the old index if the rubygems.org API fails
  during gem resolution.

=== 2.3.0 / 2014-06-10

Minor enhancements:

* Added the `open` command which allows you to inspect the source of a gem
  using your editor.
  Issue #789 by Mike Perham. Pull request #804 by Vitali F.
* The `update` command shows a summary of which gems were and were not
  updated.  Issue #544 by Mark D. Blackwell.
  Pull request #777 by Tejas Bubane.
* Improved "could not find 'gem'" error reporting.  Pull request #913 by
  Richard Schneeman.
* Gem.use_gemdeps now accepts an argument specifying the path of the gem
  dependencies file.  When the file is not found an ArgumentError is raised.
* Writing a .lock file for a gem dependencies file is now controlled by the
  --[no-]lock option.  Pull reuqest #774 by Jeremy Evans.
* Suggestion of alternate names and spelling corrections during install can be
  suppressed with the --no-suggestions option.  Issue #867 by Jimmy Cuadra.
* Added mswin64 support.  Pull request #881 by U. Nakamura.
* A gem is installable from an IO again (as in RubyGems 1.8.x and older).
  Pull request #716 by Xavier Shay.
* RubyGems no longer attempts to build extensions during activation.  Instead
  a warning is issued instructing you to run `gem pristine` which will build
  the extensions for the current platform.  Issue #796 by dunric.
* Added Gem::UserInteraction#verbose which prints when the --verbose option is
  given.  Pull request #811 by Aaron Patterson.
* RubyGems can now fetch gems from private repositories using S3.  Pull
  request #856 by Brian Palmer.
* Added Gem::ConflictError subclass of Gem::LoadError so you can distinguish
  conflicts from other problems.  Pull request #841 by Aaron Patterson.
* Cleaned up unneeded load_yaml bootstrapping in Rakefile.  Pull request #815
  by Zachary Scott.
* Improved performance of conflict resolution.  Pull request #842 by Aaron
  Patterson.
* Add documentation of "~> 0" to Gem::Version.  Issue #896 by Aaron Suggs.
* Added CONTRIBUTING file.  Pull request #849 by Mark Turner.
* Allow use of bindir in windows_stub_script in .bat
  Pull request #818 by @unak and @nobu
* Use native File::PATH_SEPARATOR and remove $ before gem env on
  Gem::Dependency#to_specs. Pull request #915 by @parkr
* RubyGems recommends SPDX IDs for licenses now.  Pull request #917 by
  Benjamin Fleischer.

Bug fixes:

* RubyGems now only fetches the latest specs to find misspellings which speeds
  up gem suggestions.  Pull request #808 by Aaron Patterson.
* The given .gem is installed again when multiple versions of the same gem
  exist in the current directory.  Bug #875 by Prem Sichanugrist.
* Local gems are preferred by name over remote gems again.  Bug #834 by
  jonforums.
* RubyGems can install local prerelease gems again.  Pull request #866 by
  Aaron Patterson.  Issue #813 by André Arko.
* RubyGems installs development dependencies correctly again.  Issue #893 by
  Jens Wille.
* RubyGems only installs prerelease versions when they are requested again.
  Issue #853 by Seth Vargo, special thanks to Zachary Scott and Ben Moss.
  Issue #884 by Nathaniel Bibler.
* Fixed RubyGems list and search command help.  Pull request #905 and #928 by
  Gabriel Gilder.
* The list of gems to uninstall is always sorted now.  Bug #918 by postmodern.
* The update command only updates exactly matching gem names now.  Bug #919 by
  postmodern.
* Gem::Server now supports prerelease versions.  Bug #857 by Marcelo Alvim.
* RubyGems no longer raises an exception immediately when gems are missing
  with RUBYGEMS_GEMDEPS.  A warning is printed instead.  Issue #886 by Michael
  Kaiser-Nyman.
* Commands using the rubygems.org API no longer try to sign-in when a
  non-rubygems API key has been chosen.  Bug #826 by Ben Sedat.
* Updated documentation of Gem::Specification#executables to indicate that
  only ruby scripts are allowed.  Bug #830 by Geoff Nixon.
* Gem dependency API supports multiple platforms for #platform and #platforms
  now.  Bug #821 by johnny5-.
* Gem dependency API supports lockfiles without explicit sources.  Bug #820 by
  johnny5-.
* Gem dependency API supports lockfiles with multiple sources.  Bug #822 by
  johnny5-, bug #851 by sumit shah.
* Gem dependency API supports lockfiles with git sources using branch, tag and
  ref.  Bug #822 by johnny5-, #931 by Christoph Blank.
* Gem dependency API no longer raises an exception when a gem does not exist
  in one of the configured sources.  Bug #897 by Michael Kaiser-Nyman.
* Gem dependency API no longer lists development dependencies in the lockfile.
  Bug #768 by Diego Viola, #916 by Santiago Pastorino.
* SSL configuration entries in ~/.gemrc are properly round-tripped.  Bug #837
  by Noah Luck Easterly.
* The environment command now shows the system configuration directory where
  the all-users gemrc lives.  Bug #827 by Ben Langfeld.
* Improved speed of conflict checking when activating gems.  Pull request #843
  by Aaron Patterson.
* Improved speed of levenshtein distance for gem suggestion misspellings.
  Pull requests #809, #812 by Aaron Patterson.
* Restored persistent connections.  Pull request #869 by Aaron Patterson.
* Reduced requests when fetching gems with the bundler API.  Pull request #773
  by Charlie Somerville.
* Reduced dependency prefetching to improve install speed.  Pull requests
  #871, #872 by Matthew Draper.
* RubyGems now avoids net/http auto-proxy detection.  Issue #824 by HINOHARA
  Hiroshi.
* Removed conversion of Gem::List (used for debugging installs) to unless
  necessary.  Pull request #870 by Aaron Patterson.
* RubyGems now prints release notes from the current release.  Bug #814 by
  André Arko.
* RubyGems allows installation of unsigned gems again with -P MediumSecurity
  and lower.  Bug #859 by Justin S. Collins.
* Fixed typo in Jim Weirich's name.  Ruby pull request #577 by Mo Khan.
* Fixed typo in Gem.datadir documentation.  Pull request #868 by Patrick
  Jones.
* Fixed File.exists? warnings.  Pull request #829 by SHIBATA Hiroshi.
* Fixed show_release_notes test for LANG=C.  Issue #862 by Luis Lavena.
* Fixed Gem::Package from IO tests on windows.  Patch from issue #861 by Luis
  Lavena.
* Check for nil extensions as BasicSpecification does not initialize them.
  Pull request #882 by André Arko.
* Fixed Gem::BasicSpecification#require_paths receives a String for
  @require_paths. Pull requrest #904 by @danielpclark
* Fixed circular require warnings.  Bug #908 by Zachary Scott.
* Gem::Specification#require_paths can no longer accidentally be an Array.
  Pull requests #904, #909 by Daniel P. Clark.
* Don't build extensions if `build_dir/extensions` isn't writable.
  Pull request #912 by @dunric
* Gem::BasicSpecification#require_paths respects default_ext_dir_for now.  Bug
  #852 by Vít Ondruch.

------------------------------------------------------------------------------
727b01a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment