Update docs for RSpec 3.

features/GemVersions.md

@@ -9,6 +9,6 @@ Which _versions_ get installed is a bit trickier.
 The rspec gem uses a [Pessimistic Version
 Constraint](http://docs.rubygems.org/read/chapter/16#page74) (e.g. "~> 2.4.0")
 to declare its dependencies on the rspec-core, rspec-expectations, and
-rspec-mocks gems. This means that when you install rspec-2.6.0, you'll get the
+rspec-mocks gems. This means that when you install rspec-2.4.0, you'll get the
 latest patch releases of rspec-core-2.4, rspec-expectations-2.4, and
 rspec-mocks-2.4, but you won't get versions >= 2.5.

features/GettingStarted.md

@@ -1,18 +1,19 @@
 ### Prerequisites
 
-* Ruby 1.8.6 or higher
+* Ruby 1.8.7 or higher (we recommend Ruby 1.9 or 2.0)
 * Rubygems 1.3.7
 
 ### Install
 
     gem install rspec
 
-This installs four gems:
+This installs five gems:
 
 * rspec
 * rspec-core
 * rspec-expectations
 * rspec-mocks
+* rspec-support
 
 The rspec-core gem installs an `rspec` executable. Run the `rspec` command with
 the `--help` flag to see the available options:
@@ -51,18 +52,16 @@ require './game'
 ...
 </pre>
 
-<pre>
-# game.rb
+    # game.rb
 
-class Game
-  def roll(pins)
-  end
+    class Game
+      def roll(pins)
+      end
 
-  def score
-    0
-  end
-end
-</pre>
+      def score
+        0
+      end
+    end
 
 Run the example and bask in the joy that is green.
 

features/README.md

@@ -5,7 +5,7 @@ part of that equation, focusing on the documentation and design aspects of TDD.
 
 ### Documentation
 
-This is the official documentation site for RSpec-2. Much of the documentation
+This is the official documentation site for RSpec. Much of the documentation
 you see here is written with [Cucumber](http://github.com/cucumber/cucumber),
 which, like RSpec, provides _executable documentation_. The Cucumber features
 you see here have all been run against RSpec's codebase, serving as
@@ -22,13 +22,15 @@ You can find documentation for rspec-1 at [http://old.rspec.info](http://old.rsp
 
 ### Mailing list
 
-[rspec-users](http://rubyforge.org/mailman/listinfo/rspec-users)<br/>
-[google group](http://groups.google.com/group/rspec) (must be a member of the rspec-users list to post)
+[rspec google group](http://groups.google.com/group/rspec)
 
-### Upgrading from RSpec-1
+### Upgrading from RSpec 2.x
 
-If you are upgrading from rspec-1, or beta versions of rspec-2, be sure to
-review the Upgrade information for each project.
+We've put a lot of effort into making the upgrade process from RSpec 2.x
+to 3.x as smooth as possible, in spite of the fact that it's our first
+chance in over 3 years to intentionally make backwards-incompatible
+changes. See the [upgrade](./upgrade) documentation for detailed
+step-by-step upgrade instructions.
 
 ### Help make this documentation better!
 

features/Upgrade.md

@@ -0,0 +1,65 @@
+RSpec 3 includes many breaking changes, but our hope is to make this
+the smoothest major-version gem upgrade you've ever done. To assist
+with that process, we've been developing RSpec 2.99 in tandem with
+RSpec 3.  Every time we make a breaking change in the master branch
+for 3.0, we've been adding a corresponding deprecation to 2.99.  This
+isn't just for APIs that have been removed; it's also for slight changes
+in edge-case semantics (in order to make RSpec more consistent) that
+some projects may rely on. Rather than just giving you a generic
+upgrade document that describes _all_ of the breaking changes
+(ost of which affect very few users!), RSpec 2.99 gives you
+a detailed upgrade checklist.
+
+In addition, [Yuji Nakayama](https://twitter.com/nkym37) has been developing
+[transpec](https://github.com/yujinakayama/transpec) -- an absolutely amazing
+tool that can automatically upgrade most RSpec suites. We've tried it on a
+few projects and have been _amazed_ at how well it works.
+
+## Step-by-step Instructions
+
+1. Ensure your test suite is already green on whatever RSpec 2.x version
+   you're already using.
+2. Install RSpec 2.99.0.beta1 (or whatever the latest 2.99 release is
+   when you go through this process).
+3. Run your test suite and ensure it's still green. (It should be, but
+   we may have made a mistake -- if it breaks anything, please report
+   a bug!). Now would be a good time to commit.
+4. You'll notice a bunch of deprecation warnings printed off at the
+   end of the spec run. These may be truncated since we don't to
+   spam you with the same deprecation warning over and over again. To
+   get the full list of deprecations, you can pipe them into a file
+   by setting the `config.deprecation_stream = 'rspec.log'` option.
+5. If you want to understand all of what is being deprecated, it's a
+   good idea to read through the deprecation messages.  In some cases,
+   you have choices -- such as continuing to use the `have` collection
+   cardinality matchers via the extracted
+   [rspec-collection_matchers](https://github.com/rspec/rspec-collection_matchers)
+   gem, or by rewriting the expectation expression to something like
+   `expect(list.size).to eq(3)`.
+6. `gem install transpec` (Note that this need not go into your
+   `Gemfile`: you run `transpec` as a standalone executable
+    outside the context of your bundle).
+7. Run transpec on your project. Check `transpec --help` or
+   [the README](https://github.com/yujinakayama/transpec#transpec)
+   for a full list of options.
+8. Run the test suite (it should still be green but it's always good to
+   check!) and commit.
+9. If there are any remaining deprecation warnings (transpec doesn't
+   quite handle all of the warnings you may get), deal with them.
+9. Once you've got a deprecation-free test suite running against RSpec
+   2.99, you're ready to upgrade to RSpec 3. Install RSpec 3.0.0.beta1
+   (or whatever the latest 3.x release is when you go through this process).
+10. Run your test suite. It should still be green. If anything fails,
+    please open a Github issue -- we consider it a bug[^foot_1]! Note
+    that you may still get a few additional deprecation warnings on
+    RSpec 3 that weren't present on 2.99.  This is normal -- there are
+    a few things we couldn't easily deprecate in 2.99 and remove in 3.0,
+    so they trigger deprecations in 3.0 with the plan to remove them in
+    RSpec 4.
+11. Commit and enjoy using the latest RSpec release!
+
+[^foot_1]: There is one caveat to that, though: we only consider it a bug
+  to the extent that your test suite uses the RSpec APIs as they are
+  documented. The dynamic nature of Ruby makes it possible to use RSpec
+  in ways that we can't support.
+