I really like the RubyGems rational versioning policy ( http://docs.rubygems.org/read/chapter/7 ) and wish everyone followed that.
I think it might be harder for gems like Rails that are actually metagems. But I do agree that it's surprising for a move from 2.3.5 to 2.3.6 to break backwards compatibility. Have we forgotten Ruby's ideal of the principle of least surprise?
Perhaps a good compromise between what Rails is currently doing and what it should be doing is to add a fourth version number. When the fourth version number changes, you can rest assured that the change is backwards compatible. (However, there is always the danger that some plugin/engine/gem author monkey-patched a part of Rails which could make their code break during a "backwards-compatible" upgrade to Rails.)
I like the 4th version number idea. Since everybody in the Ruby community seems to think that it's okay for major breaking changes to occur on a minor version bump, let's adjust policy to match practice rather than the other way around. Let's call the first number the "political" number, the second the "major", the third "minor" and fourth "patch".
I would say this is true for Rails, but I think (or hope!) there is a consensus (or at least a majority opinion?) among Ruby developers that any gem version that breaks compatibility should change the major (1st) version number. Otherwise, the ~> operator used by bundler and RubyGems becomes meaningless.
All of the gems that I publish strictly follow the rule that any change that could break code will bump the 1st version number, any change that adds features/behavior will bump the 2nd version number, and any change that has no interface effect (bug fixes, performance enhancements, documentation tweaks) will bump the 3rd version number.
But luckily ~> isn't completely broken. In my rails apps I use ~> x.y.z to ensure that I only pull in patch level changes.
Here's my suggestions:
- make a breaking change to the gem versioning system to force all library, framework and gem authors to use versions properly. If you make a breaking change in your API, you MUST change the major number. Rails made a couple of breaking changes in the transition from 2.3.5 to 2.3.6, for Pete's sake, and a huge number of breaking changes in any of their 'minor number' upgrades. Many gems are even worse. Yes, this is going to cause massive version number inflation. So what? Chrome increments their major number even faster and with less reason.
- If a change to a plugin breaks on an older version of Rails, tell the authors so they can update their gemspec so that other users of older versions of Rails don't get the update.
- Make it easier to contribute to the documentation. It's already pretty easy, but make it easier. Add an "edit this page" link on every documentation page that goes to the corresponding "edit this file" in the docrails project in github.
- 90% of the "documentation" for Rails can be found randomly scattered across the internet on blog posts. Of course, these are usually out of date. "Encourage" (with a stick, perhaps) people to stop doing this and instead to add to the documentation. If that's not appropriate, stack overflow or some other blessed site. Not a random blog post that's never going to get updated and will probably disappear in a few years.