diff --git a/features/.nav b/features/.nav
index b02b760e94..5b4834b185 100644
--- a/features/.nav
+++ b/features/.nav
@@ -4,8 +4,20 @@
 - hooks:
   - before_and_after_hooks.feature
   - around_hooks.feature
+- pending:
+  - pending_examples.feature
+- subject:
+  - implicit_subject.feature
+  - explicit_subject.feature
+  - attribute_of_subject.feature
+  - implicit_receiver.feature
 - metadata:
   - described_class.feature
+- filtering:
+  - inclusion_filters.feature
+  - exclusion_filters.feature
+  - implicit_filters.feature
+  - run_all_when_everything_filtered.feature
 - command_line:
   - configure.feature
   - example_name_option.feature
@@ -20,25 +32,15 @@
   - custom_settings.feature
 - expectation_framework_integration:
   - configure_expectation_framework.feature
-- filtering:
-  - inclusion_filters.feature
-  - exclusion_filters.feature
-  - implicit_filters.feature
-  - run_all_when_everything_filtered.feature
-- formatters:
-  - custom_formatter.feature
 - mock_framework_integration:
   - use_rspec.feature
   - use_flexmock.feature
   - use_mocha.feature
   - use_rr.feature
   - use_any_framework.feature
-- pending:
-  - pending_examples.feature
+- formatters:
+  - custom_formatter.feature
 - spec_files:
   - arbitrary_file_suffix.feature
-- subject:
-  - implicit_subject.feature
-  - explicit_subject.feature
-  - attribute_of_subject.feature
-  - implicit_receiver.feature
+- Changelog.md
+- Upgrade_notes.md
diff --git a/features/Changelog.md b/features/Changelog.md
new file mode 100644
index 0000000000..0a582a747c
--- /dev/null
+++ b/features/Changelog.md
@@ -0,0 +1,154 @@
+## rspec-core release history (incomplete)
+
+### 2.3.0 / 2010-12-12
+
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.2.1...v2.3.0)
+
+* Enhancements
+  * tell autotest to use "rspec2" if it sees a .rspec file in the project's
+    root directory
+    * replaces the need for ./autotest/discover.rb, which will not work with
+      all versions of ZenTest and/or autotest
+  * config.expect_with
+    * :rspec          # => rspec/expectations
+    * :stdlib         # => test/unit/assertions
+    * :rspec, :stdlib # => both
+
+* Bug fixes
+  * fix dev Gemfile to work on non-mac-os machines (Lake Denman)
+  * ensure explicit subject is only eval'd once (Laszlo Bacsi)
+
+### 2.2.1 / 2010-11-28
+
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.2.0...v2.2.1)
+
+* Bug fixes
+  * alias_method instead of override Kernel#method_missing (John Wilger)
+  * changed --autotest to --tty in generated command (MIKAMI Yoshiyuki) 
+  * revert change to debugger (had introduced conflict with Rails)
+    * also restored --debugger/-debug option
+
+### 2.2.0 / 2010-11-28
+
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.1.0...v2.2.0)
+
+* Deprecations/changes
+  * --debug/-d on command line is deprecated and now has no effect
+  * win32console is now ignored; Windows users must use ANSICON for color support
+    (Bosko Ivanisevic)
+
+* Enhancements
+  * When developing locally rspec-core now works with the rspec-dev setup or your local gems
+  * Raise exception with helpful message when rspec-1 is loaded alongside
+    rspec-2 (Justin Ko)
+  * debugger statements _just work_ as long as ruby-debug is installed
+    * otherwise you get warned, but not fired
+  * Expose example.metadata in around hooks
+  * Performance improvments (see [Upgrade.markdown](https://github.com/rspec/rspec-core/blob/master/Upgrade.markdown))
+
+* Bug fixes
+  * Make sure --fail-fast makes it across drb
+  * Pass -Ilib:spec to rcov
+
+### 2.1.0 / 2010-11-07
+
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.0.1...v2.1.0)
+
+* Enhancments
+  * Add skip_bundler option to rake task to tell rake task to ignore the
+    presence of a Gemfile (jfelchner)
+  * Add gemfile option to rake task to tell rake task what Gemfile to look
+    for (defaults to 'Gemfile')
+  * Allow passing caller trace into Metadata to support extensions (Glenn
+    Vanderburg)
+  * Add deprecation warning for Spec::Runner.configure to aid upgrade from
+    RSpec-1
+  * Add deprecated Spec::Rake::SpecTask to aid upgrade from RSpec-1
+  * Add 'autospec' command with helpful message to aid upgrade from RSpec-1
+  * Add support for filtering with tags on CLI (Lailson Bandeira)
+  * Add a helpful message about RUBYOPT when require fails in bin/rspec
+    (slyphon)
+  * Add "-Ilib" to the default rcov options (Tianyi Cui)
+  * Make the expectation framework configurable (default rspec, of course)
+    (Justin Ko)
+  * Add 'pending' to be conditional (Myron Marston)
+  * Add explicit support for :if and :unless as metadata keys for conditional run
+    of examples (Myron Marston)
+  * Add --fail-fast command line option (Jeff Kreeftmeijer)
+
+* Bug fixes
+  * Eliminate stack overflow with "subject { self }"
+  * Require 'rspec/core' in the Raketask (ensures it required when running rcov)
+
+### 2.0.1 / 2010-10-18
+
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.0.0...v2.0.1)
+
+* Bug fixes
+  * Restore color when using spork + autotest
+  * Pending examples without docstrings render the correct message (Josep M. Bach)
+  * Fixed bug where a failure in a spec file ending in anything but _spec.rb would
+    fail in a confusing way.
+  * Support backtrace lines from erb templates in html formatter (Alex Crichton)
+
+### 2.0.0 / 2010-10-10
+
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.0.0.rc...v2.0.0)
+
+* RSpec-1 compatibility
+  * Rake task uses ENV["SPEC"] as file list if present
+
+* Bug fixes
+  * Bug Fix: optparse --out foo.txt (Leonardo Bessa)
+  * Suppress color codes for non-tty output (except autotest)
+
+### 2.0.0.rc / 2010-10-05
+
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.0.0.beta.22...v2.0.0.rc)
+
+* Enhancements
+  * implicitly require unknown formatters so you don't have to require the
+    file explicitly on the commmand line (Michael Grosser)
+  * add --out/-o option to assign output target
+  * added fail_fast configuration option to abort on first failure
+  * support a Hash subject (its([:key]) { should == value }) (Josep M. Bach)
+
+* Bug fixes
+  * Explicitly require rspec version to fix broken rdoc task (Hans de Graaff)
+  * Ignore backtrace lines that come from other languages, like Java or
+    Javascript (Charles Lowell)
+  * Rake task now does what is expected when setting (or not setting)
+    fail_on_error and verbose
+  * Fix bug in which before/after(:all) hooks were running on excluded nested
+    groups (Myron Marston)
+  * Fix before(:all) error handling so that it fails examples in nested groups,
+    too (Myron Marston)
+
+### 2.0.0.beta.22 / 2010-09-12
+
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.0.0.beta.20...v2.0.0.beta.22)
+
+* Enhancements
+  * removed at_exit hook
+  * CTRL-C stops the run (almost) immediately
+    * first it cleans things up by running the appropriate after(:all) and after(:suite) hooks
+    * then it reports on any examples that have already run
+  * cleaned up rake task
+    * generate correct task under variety of conditions
+    * options are more consistent
+    * deprecated redundant options
+  * run 'bundle exec autotest' when Gemfile is present
+  * support ERB in .rspec options files (Justin Ko)
+  * depend on bundler for development tasks (Myron Marston)
+  * add example_group_finished to formatters and reporter (Roman Chernyatchik)
+
+* Bug fixes
+  * support paths with spaces when using autotest (Andreas Neuhaus)
+  * fix module_exec with ruby 1.8.6 (Myron Marston)
+  * remove context method from top-level
+    * was conflicting with irb, for example
+  * errors in before(:all) are now reported correctly (Chad Humphries)
+
+* Removals
+  * removed -o --options-file command line option
+    * use ./.rspec and ~/.rspec
diff --git a/features/Upgrade_notes.md b/features/Upgrade_notes.md
new file mode 100644
index 0000000000..3698f89ee7
--- /dev/null
+++ b/features/Upgrade_notes.md
@@ -0,0 +1,345 @@
+# rspec-core-2.3
+
+## autotest integration
+
+Add a .rspec file to the project's root directory to tell RSpec to tell
+Autotest to use RSpec's specialized Autotest class.
+
+NOTE that rspec-core-2.0, 2.1, and 2.2 required an autotest/discover.rb file in
+the project's root directory. This worked with some, but not all versions of
+autotest and/or the autotest command that ships with ZenTest. This new approach
+will work regardless of which version of autotest/ZenTest you are using.
+
+## config.expect_with
+
+Use this to configure RSpec to use rspec/expectations (default),
+test/unit/assertions, or both:
+
+    RSpec.configure do |config|
+      config.expect_with :rspec          # => rspec/expectations
+      config.expect_with :stdlib         # => test/unit/assertions
+      config.expect_with :rspec, :stdlib # => both
+    end
+
+# rspec-core-2.2
+
+## FASTER!
+
+Made several small optimizations that all add up to a considerable improvement
+in performance. Using a simple benchmark:
+
+    generate 5000 example groups,
+    each with one example,
+    each with one passing expectation
+
+Run using ruby-1.9.2 on Mac OS X w/ 3.06 G
+
+* rspec-2.1
+  * loaded in 0.85 on avg
+  * ran in 2.61 on avg
+* rspec-2.2
+  * loaded in 0.73 on avg (~15% improvement)
+  * ran in 0.94 on avg    (~64% improvement**)
+    
+** this does _not_ mean your suite will be 64% faster, but it does mean that
+   the overhead incurred by RSpec in your suite should be roughly 64% less.
+
+## Command line
+
+### --debug/-d is now deprecated
+
+This command line option is now has no effect (other than a deprecation
+warning). To use the debugger, just add a `debugger` statement anywhere in your
+code. As long as you have ruby-debug installed, it will just work. If you
+don't, then you'll get a friendly warning telling you what's going on, but
+execution will continue.
+
+# rspec-core-2.1
+
+## Command line
+
+### `--tags`
+
+Now you can tag groups and examples using metadata and access those tags from
+the command line. So if you have a group with `:foo => true`:
+
+    describe "something", :foo => true do
+      it "does something" do
+        # ...
+      end
+    end
+
+... now you can run just that group like this:
+
+    rspec spec --tags foo
+
+### `--fail-fast`
+
+Add this flag to the command line to tell rspec to clean up and exit after the
+first failure:
+
+    rspec spec --fail-fast
+
+## Metata/filtering
+
+### :if and :unless keys
+
+Use :if and :unless keys to conditionally run examples with simple boolean
+expressions:
+
+    describe "something" do
+      it "does something", :if => RUBY_VERSION == 1.8.6 do
+        # ...
+      end
+      it "does something", :unless => RUBY_VERSION == 1.8.6 do
+        # ...
+      end
+    end
+
+## Conditionally 'pending' examples
+
+Make examples pending based on a condition.  This is most useful when you
+have an example that runs in multiple contexts and fails in one of those due to
+a bug in a third-party dependency that you expect to be fixed in the future.
+
+    describe "something" do
+      it "does something that doesn't yet work right on JRuby" do
+        pending("waiting for the JRuby team to fix issue XYZ", :if => RUBY_PLATFORM == 'java') do
+          # the content of your spec
+        end
+      end
+    end
+
+This example would run normally on all ruby interpretters except JRuby.  On JRuby,
+it uses the block form of `pending`, which causes the example to still be run and
+will remain pending as long as it fails.  In the future, if you upgraded your
+JRuby installation to a newer release that allows the example to pass, RSpec
+will report it as a failure (`Expected pending '...' to fail.  No Error was raised.`),
+so that know that you can remove the call to `pending`.
+
+# New features in rspec-core-2.0
+
+### Runner
+
+The new runner for rspec-2 comes from Micronaut.
+
+### Metadata!
+
+In rspec-2, every example and example group comes with metadata information
+like the file and line number on which it was declared, the arguments passed to
+`describe` and `it`, etc.  This metadata can be appended to through a hash
+argument passed to `describe` or `it`, allowing us to pre and post-process
+each example in a variety of ways.
+
+### Filtering
+
+The most obvious use is for filtering the run. For example:
+
+    # in spec/spec_helper.rb
+    RSpec.configure do |c|
+      c.filter_run :focus => true
+    end
+
+    # in any spec file
+    describe "something" do
+      it "does something", :focus => true do
+        # ....
+      end
+    end
+
+When you run the `rspec` command, rspec will run only the examples that have
+`:focus => true` in the hash. 
+
+You can also add `run_all_when_everything_filtered` to the config:
+
+    RSpec.configure do |c|
+      c.filter_run :focus => true
+      c.run_all_when_everything_filtered = true
+    end
+
+Now if there are no examples tagged with `:focus => true`, all examples
+will be run. This makes it really easy to focus on one example for a
+while, but then go back to running all of the examples by removing that
+argument from `it`. Works with `describe` too, in which case it runs
+all of the examples in that group.
+
+The configuration will accept a lambda, which provides a lot of flexibility
+in filtering examples. Say, for example, you have a spec for functionality that
+behaves slightly differently in Ruby 1.8 and Ruby 1.9. We have that in
+rspec-core, and here's how we're getting the right stuff to run under the
+right version:
+
+    # in spec/spec_helper.rb
+    RSpec.configure do |c|
+      c.exclusion_filter = { :ruby => lambda {|version|
+        !(RUBY_VERSION.to_s =~ /^#{version.to_s}/)
+      }}
+    end
+
+    # in any spec file
+    describe "something" do
+      it "does something", :ruby => 1.8 do
+        # ....
+      end
+
+      it "does something", :ruby => 1.9 do
+        # ....
+      end
+    end
+
+In this case, we're using `exclusion_filter` instead of `filter_run` or
+`filter`, which indicate _inclusion_ filters. So each of those examples is
+excluded if we're _not_ running the version of Ruby they work with.
+
+### Shared example groups
+
+Shared example groups are now run in a nested group within the including group
+(they used to be run in the same group). Nested groups inherit `before`, `after`,
+`around`, and `let` hooks, as well as any methods that are defined in the parent
+group.
+
+This new approach provides better encapsulation, better output, and an
+opportunity to add contextual information to the shared group via a block
+passed to `it_should_behave_like`.
+
+See [features/example\_groups/shared\_example\_group.feature](http://github.com/rspec/rspec-core/blob/master/features/example_groups/shared_example_group.feature) for more information.
+
+NOTICE: The including example groups no longer have access to any of the
+methods, hooks, or state defined inside a shared group. This will break specs
+that were using shared example groups to extend the behavior of including
+groups in any way besides their intended purpose: to add examples to a group.
+
+# Upgrading from rspec-1.x
+
+### rspec command
+
+The command to run specs is now `rspec` instead of `spec`.
+
+    rspec ./spec
+
+#### Co-habitation of rspec-1 and rspec-2
+
+Early beta versions of RSpec-2 included a `spec` command, which conflicted with
+the RSpec-1 `spec` command because RSpec-1's was installed by the rspec gem,
+while RSpec-2's is installed by the rspec-core gem.
+
+If you installed one of these early versions, the safest bet is to uninstall
+rspec-1 and rspec-core-2, and then reinstall both. After you do this, you will
+be able to run rspec-2 like this:
+
+    rspec ./spec
+
+... and rspec-1 like this:
+
+    spec _1.3.1_ ./spec
+
+Rubygems inspects the first argument to any gem executable to see if it's
+formatted like a version number surrounded by underscores. If so, it uses that
+version (e.g.  `1.3.1`). If not, it uses the most recent version (e.g.
+`2.0.0`).
+
+### rake task
+
+A few things changed in the Rake task used to run specs:
+
+1.  The file in which it is defined changed from `spec/rake/spectask` to
+    `rspec/core/rake_task`
+
+2.  The `spec_opts` accessor has been deprecated in favor of `rspec_opts`. Also,
+    the `rspec` command no longer supports the `--options` command line option
+    so the options must be embedded directly in the Rakefile, or stored in the
+    `.rspec` files mentioned above.
+    
+3.  In RSpec-1, the rake task would read in rcov options from an `rcov.opts`
+    file. This is ignored by RSpec-2. RCov options are now set directly on the Rake
+    task:
+
+        RSpec::Core::RakeTask.new(:rcov) do |t|
+          t.rcov_opts =  %q[--exclude "spec"]
+        end
+
+3.  The `spec_files` accessor has been replaced by `pattern`.
+
+        # rspec-1
+        require 'spec/rake/spectask'
+
+        Spec::Rake::SpecTask.new do |t|
+          t.spec_opts = ['--options', "\"spec/spec.opts\""]
+          t.spec_files = FileList['spec/**/*.rb']
+        end
+
+        # rspec-2
+        require 'rspec/core/rake_task'
+
+        RSpec::Core::RakeTask.new do |t|
+          t.rspec_opts = ["-c", "-f progress", "-r ./spec/spec_helper.rb"]
+          t.pattern = 'spec/**/*_spec.rb'
+        end
+
+### autotest
+
+RSpec-2 works with autotest as follows:
+
+    rspec --configure autotest
+
+This adds `./autotest/discover.rb` with:
+
+    Autotest.add_discovery { "rspec2" }
+
+Now, on the command line just type:
+
+    autotest
+
+Or, if you're using bundler:
+
+    bundle exec autotest
+
+The `autospec` command is a thing of the past. 
+
+### RSpec is the new Spec
+
+The root namespace (top level module) is now `RSpec` instead of `Spec`, and
+the root directory under `lib` within all of the `rspec` gems is `rspec` instead of `spec`.
+
+### Configuration
+
+Typically in `spec/spec_helper.rb`, configuration is now done like this:
+
+    RSpec.configure do |c|
+      # ....
+    end
+
+### .rspec
+
+Command line options can be persisted in a `.rspec` file in a project. You
+can also store a `.rspec` file in your home directory (`~/.rspec`) with global
+options. Precedence is:
+
+    command line
+    ./.rspec
+    ~/.rspec
+
+### `context` is no longer a top-level method
+
+We removed `context` from the main object because it was creating conflicts with
+IRB and some users who had `Context` domain objects. `describe` is still there,
+so if you want to use `context` at the top level, just alias it:
+
+    alias :context :describe
+
+Of course, you can still use `context` to declare a nested group:
+
+    describe "something" do
+      context "in some context" do
+        it "does something" do
+          # ...
+        end
+      end
+    end
+
+### `$KCODE` no longer set implicitly to `'u'`
+
+In RSpec-1, the runner set `$KCODE` to `'u'`, which impacts, among other
+things, the behaviour of Regular Expressions when applied to non-ascii
+characters. This is no longer the case in RSpec-2.
+