Merge josevalim/deprecations branch.

I maintained on purpose the DeprecatedUrlOptions in ActionMailer and the Deprecated configuration in Railties because they were already addressed by Piotr in his RSoC work.

17 files changed, 259 insertions, 146 deletions

diff --git a/.yardopts b/.yardopts
new file mode 100644
index 0000000000..4f89247bbb
--- /dev/null
+++ b/.yardopts
@@ -0,0 +1,3 @@
+--exclude /templates/
+--quiet
+act*/lib/**/*.rb
diff --git a/Rakefile b/Rakefile
index 092d854c35..5065fb286b 100644
--- a/Rakefile
+++ b/Rakefile
@@ -144,6 +144,7 @@ task :rdoc do
   FileUtils.copy "activerecord/examples/associations.png", "doc/rdoc/files/examples/associations.png"
 end
 
+desc 'Bump all versions to match version.rb'
 task :update_versions do
   require File.dirname(__FILE__) + "/version"
 
diff --git a/actionmailer/CHANGELOG b/actionmailer/CHANGELOG
index 3b82023641..62c1402346 100644
--- a/actionmailer/CHANGELOG
+++ b/actionmailer/CHANGELOG
@@ -1,19 +1,9 @@
-*Rails 3.0.0 (unreleased)*
+*Rails 3.1.0 (unreleased)*
 
 * No changes
 
 
-*Rails 3.0.0 [release candidate 2] (August 23rd, 2010)*
-
-* No changes
-
-
-*Rails 3.0.0 [release candidate] (July 26th, 2010)*
-
-* No changes
-
-
-*Rails 3.0.0 [beta 4] (June 8th, 2010)*
+*Rails 3.0.0 (August 29, 2010)*
 
 * subject is automatically looked up on I18n using mailer_name and action_name as scope as in t(".subject") [JK]
 
@@ -21,16 +11,10 @@
 
 * Added ability to pass Proc objects to the defaults hash [ML]
 
-
-*Rails 3.0.0 [beta 3] (April 13th, 2010)*
-
 * Removed all quoting.rb type files from ActionMailer and put Mail 2.2.0 in instead [ML]
 
 * Lot of updates to various test cases that now work better with the new Mail and so have different expectations
 
-
-*Rails 3.0.0 [beta 2] (April 1st, 2010)*
-
 * Added interceptors and observers from Mail [ML]
 
     ActionMailer::Base.register_interceptor calls Mail.register_interceptor
@@ -48,9 +32,6 @@
 
 * Whole new API added with tests.  See base.rb for full details.  Old API is deprecated.
 
-
-*Rails 3.0.0 [beta 1] (February 4, 2010)*
-
 * The Mail::Message class has helped methods for all the field types that return 'common' defaults for the common use case, so to get the subject, mail.subject will give you a string, mail.date will give you a DateTime object, mail.from will give you an array of address specs (mikel@test.lindsaar.net) etc.  If you want to access the field object itself, call mail[:field_name] which will return the field object you want, which you can then chain, like mail[:from].formatted
 
 * Mail#content_type now returns the content_type field as a string. If you want the mime type of a mail, then you call Mail#mime_type (eg, text/plain), if you want the parameters of the content type field, you call Mail#content_type_parameters which gives you a hash, eg {'format' => 'flowed', 'charset' => 'utf-8'}
diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG
index 00cde0c652..75d0632a6d 100644
--- a/actionpack/CHANGELOG
+++ b/actionpack/CHANGELOG
@@ -1,4 +1,9 @@
-*Rails 3.0.0 (unreleased)*
+*Rails 3.1.0 (unreleased)*
+
+* No changes
+
+
+*Rails 3.0.0 (August 29, 2010)*
 
 * password_field renders with nil value by default making the use of passwords secure by default, if you want to render you should do for instance f.password_field(:password, :value => @user.password) [Santiago Pastorino]
 
@@ -6,18 +11,12 @@
 
 * Add clear_helpers as a way to clean up all helpers added to this controller, maintaing just the helper with the same name as the controller. [José Valim]
 
-
-*Rails 3.0.0 [release candidate 2] (August 23rd, 2010)*
-
 * See http://github.com/rails/rails/compare/v3.0.0_RC...v3.0.0_RC2 for gory details
 
 * Support routing constraints in functional tests. [Andrew White]
 
 * Add a header that tells Internet Explorer (all versions) to use the best available standards support. [Yehuda Katz]
 
-
-*Rails 3.0.0 [release candidate] (July 26th, 2010)*
-
 * Allow stylesheet/javascript extensions to be changed through railties. [Josh Kalderimis]
 
 * link_to, button_to, and tag/tag_options now rely on html_escape instead of escape_once. [fxn]
@@ -51,9 +50,6 @@
 
 * Removed textilize, textilize_without_paragraph and markdown helpers. [Santiago Pastorino]
 
-
-*Rails 3.0.0 [beta 4] (June 8th, 2010)*
-
 * Remove middleware laziness [José Valim]
 
 * Make session stores rely on request.cookie_jar and change set_session semantics to return the cookie value instead of a boolean. [José Valim]
@@ -70,9 +66,6 @@
 
 * Changed translate helper so that it doesn’t mark every translation as safe HTML. Only keys with a "_html" suffix and keys named "html" are considered to be safe HTML. All other translations are left untouched. [Craig Davey]
 
-
-*Rails 3.0.0 [beta 3] (April 13th, 2010)*
-
 * New option :as added to form_for allows to change the object name. The old <% form_for :client, @post %> becomes <% form_for @post, :as => :client %> [spastorino]
 
 * Removed verify method in controllers. [JV]
@@ -107,9 +100,6 @@
   "HEAD" and #request_method returns "GET" in HEAD requests). This
   is for compatibility with Rack::Request [YK]
 
-
-*Rails 3.0.0 [beta 2] (April 1st, 2010)*
-
 * #concat is now deprecated in favor of using <%= %> helpers [YK]
 
 * Block helpers now return Strings, so you can use <%= form_for @foo do |f| %>.
@@ -138,9 +128,6 @@
     # for just url_for
     include Rails.application.router.url_for
 
-
-*Rails 3.0.0 [beta 1] (February 4, 2010)*
-
 * Fixed that PrototypeHelper#update_page should return html_safe [DHH]
 
 * Fixed that much of DateHelper wouldn't return html_safe? strings [DHH]
diff --git a/activemodel/CHANGELOG b/activemodel/CHANGELOG
index 20eb1c9ad2..9c65778b59 100644
--- a/activemodel/CHANGELOG
+++ b/activemodel/CHANGELOG
@@ -1,30 +1,14 @@
-*Rails 3.0.0 (unreleased)*
+*Rails 3.1.0 (unreleased)*
 
 * No changes
 
 
-*Rails 3.0.0 [release candidate 2] (August 23rd, 2010)*
-
-* No changes
-
-
-*Rails 3.0.0 [release candidate] (July 26th, 2010)*
+*Rails 3.0.0 (August 29, 2010)*
 
 * Added ActiveModel::MassAssignmentSecurity [Eric Chapweske, Josh Kalderimis]
 
-
-*Rails 3.0.0 [beta 4] (June 8th, 2010)*
-
 * JSON supports a custom root option: to_json(:root => 'custom')  #4515 [Jatinder Singh]
 
-
-*Rails 3.0.0 [beta 3] (April 13th, 2010)*
-
-* No changes
-
-
-*Rails 3.0.0 [beta 2] (April 1st, 2010)*
-
 * #new_record? and #destroyed? were removed from ActiveModel::Lint. Use
   persisted? instead. A model is persisted if it's not a new_record? and it was
   not destroyed? [MG]
@@ -37,19 +21,15 @@
 * #to_key was added to ActiveModel::Lint so we can generate DOM IDs for
   AMo objects with composite keys [MG]
 
-
-*Rails 3.0.0 [beta 1] (February 4, 2010)*
-
 * ActiveModel::Observer#add_observer!
 
   It has a custom hook to define after_find that should really be in a
   ActiveRecord::Observer subclass:
 
-	  def add_observer!(klass)
-	    klass.add_observer(self)
-	    klass.class_eval 'def after_find() end' unless
-				klass.respond_to?(:after_find)
-	  end
+    def add_observer!(klass)
+      klass.add_observer(self)
+      klass.class_eval 'def after_find() end' unless klass.respond_to?(:after_find)
+    end
 
 * Change the ActiveModel::Base.include_root_in_json default to true for Rails 3 [DHH]
 
diff --git a/activerecord/CHANGELOG b/activerecord/CHANGELOG
index 262db3c5ca..62f1470287 100644
--- a/activerecord/CHANGELOG
+++ b/activerecord/CHANGELOG
@@ -1,14 +1,9 @@
-*Rails 3.0.0 (unreleased)*
+*Rails 3.1.0 (unreleased)*
 
 * No changes
 
 
-*Rails 3.0.0 [release candidate 2] (August 23rd, 2010)*
-
-* No changes
-
-
-*Rails 3.0.0 [release candidate] (July 26th, 2010)*
+*Rails 3.0.0 (August 29, 2010)*
 
 * Changed update_attribute to not run callbacks and update the record directly in the database [Neeraj Singh]
 
@@ -20,9 +15,6 @@
 
 * PostgreSQL: ensure the database time zone matches Ruby's time zone #4895 [Aaron Patterson]
 
-
-*Rails 3.0.0 [beta 4] (June 8th, 2010)*
-
 * Fixed that ActiveRecord::Base.compute_type would swallow NoMethodError #4751 [Andrew Bloomgarden, Andrew White]
 
 * Add index length support for MySQL. #1852 [Emili Parreno, Pratik Naik]
@@ -47,9 +39,6 @@
 
 * Observers can prevent records from saving by returning false, just like before_save and friends.  #4087 [Mislav Marohnić]
 
-
-*Rails 3.0.0 [beta 3] (April 13th, 2010)*
-
 * Add Relation extensions. [Pratik Naik]
 
   users = User.where(:admin => true).extending(User::AdminPowers)
@@ -64,9 +53,6 @@
 
 * Silenced "SHOW FIELDS" and "SET SQL_AUTO_IS_NULL=0" statements from the MySQL driver to improve log signal to noise ration in development [DHH]
 
-
-*Rails 3.0.0 [Beta 1] (February 4th, 2010)*
-
 * PostgreSQLAdapter: set time_zone to UTC when Base.default_timezone == :utc so that Postgres doesn't incorrectly offset-adjust values inserted into TIMESTAMP WITH TIME ZONE columns. #3777 [Jack Christensen]
 
 * Allow relations to be used as scope.
diff --git a/activerecord/activerecord.gemspec b/activerecord/activerecord.gemspec
index 0ed88a06e2..1387d6e288 100644
--- a/activerecord/activerecord.gemspec
+++ b/activerecord/activerecord.gemspec
@@ -23,6 +23,6 @@ Gem::Specification.new do |s|
 
   s.add_dependency('activesupport', version)
   s.add_dependency('activemodel',   version)
-  s.add_dependency('arel',          '~> 1.0.0')
+  s.add_dependency('arel',          '~> 1.0.1')
   s.add_dependency('tzinfo',        '~> 0.3.23')
 end
diff --git a/activeresource/CHANGELOG b/activeresource/CHANGELOG
index 7fc621f005..37da2a711c 100644
--- a/activeresource/CHANGELOG
+++ b/activeresource/CHANGELOG
@@ -1,30 +1,12 @@
-*Rails 3.0.0 (unreleased)*
+*Rails 3.1.0 (unreleased)*
 
 * No changes
 
 
-*Rails 3.0.0 [release candidate 2] (August 23rd, 2010)*
-
-* No changes
-
-
-*Rails 3.0.0 [release candidate] (July 26th, 2010)*
-
-* No changes
-
-
-*Rails 3.0.0 [beta 4] (June 8th, 2010)*
+*Rails 3.0.0 (August 29, 2010)*
 
 * JSON: set Base.include_root_in_json = true to include a root value in the JSON: {"post": {"title": ...}}. Mirrors the Active Record option.  [Santiago Pastorino]
 
-
-*Rails 3.0.0 [beta 3] (April 13th, 2010)*
-
-* No changes
-
-
-*Rails 3.0.0 [beta 1] (February 4, 2010)*
-
 * Add support for errors in JSON format.  #1956 [Fabien Jakimowicz]
 
 * Recognizes 410 as Resource Gone. #2316 [Jordan Brough, Jatinder Singh]
diff --git a/activeresource/lib/active_resource/http_mock.rb b/activeresource/lib/active_resource/http_mock.rb
index 8753a21835..ddd3fb1f5d 100644
--- a/activeresource/lib/active_resource/http_mock.rb
+++ b/activeresource/lib/active_resource/http_mock.rb
@@ -29,7 +29,8 @@ module ActiveResource
   #
   # In order for a mock to deliver its content, the incoming request must match by the <tt>http_method</tt>,
   # +path+ and <tt>request_headers</tt>.  If no match is found an InvalidRequestError exception
-  # will be raised letting you know you need to create a new mock for that request.
+  # will be raised showing you what request it could not find a response for and also what requests and response
+  # pairs have been recorded so you can create a new mock for that request.
   #
   # ==== Example
   #   def setup
@@ -97,10 +98,79 @@ module ActiveResource
         @@responses ||= []
       end
 
-      # Accepts a block which declares a set of requests and responses for the HttpMock to respond to. See the main
-      # ActiveResource::HttpMock description for a more detailed explanation.
-      def respond_to(pairs = {}) #:yields: mock
-        reset!
+      # Accepts a block which declares a set of requests and responses for the HttpMock to respond to in
+      # the following format:
+      # 
+      #   mock.http_method(path, request_headers = {}, body = nil, status = 200, response_headers = {})
+      # 
+      # === Example
+      # 
+      #   @matz  = { :id => 1, :name => "Matz" }.to_xml(:root => "person")
+      #   ActiveResource::HttpMock.respond_to do |mock|
+      #     mock.post   "/people.xml",   {}, @matz, 201, "Location" => "/people/1.xml"
+      #     mock.get    "/people/1.xml", {}, @matz
+      #     mock.put    "/people/1.xml", {}, nil, 204
+      #     mock.delete "/people/1.xml", {}, nil, 200
+      #   end
+      # 
+      # Alternatively, accepts a hash of <tt>{Request => Response}</tt> pairs allowing you to generate
+      # these the following format:
+      # 
+      #   ActiveResource::Request.new(method, path, body, request_headers)
+      #   ActiveResource::Response.new(body, status, response_headers)
+      # 
+      # === Example
+      # 
+      # Request.new(:#{method}, path, nil, request_headers)
+      # 
+      #   @matz  = { :id => 1, :name => "Matz" }.to_xml(:root => "person")
+      #
+      #   create_matz      = ActiveResource::Request.new(:post, '/people.xml', @matz, {})
+      #   created_response = ActiveResource::Response.new("", 201, {"Location" => "/people/1.xml"})
+      #   get_matz         = ActiveResource::Request.new(:get, '/people/1.xml', nil)
+      #   ok_response      = ActiveResource::Response.new("", 200, {})
+      # 
+      #   pairs = {create_matz => created_response, get_matz => ok_response}
+      # 
+      #   ActiveResource::HttpMock.respond_to(pairs)
+      #
+      # Note, by default, every time you call +respond_to+, any previous request and response pairs stored
+      # in HttpMock will be deleted giving you a clean slate to work on.
+      # 
+      # If you want to override this behaviour, pass in +false+ as the last argument to +respond_to+
+      # 
+      # === Example
+      # 
+      #   ActiveResource::HttpMock.respond_to do |mock|
+      #     mock.send(:get, "/people/1", {}, "XML1")
+      #   end
+      #   ActiveResource::HttpMock.responses.length #=> 1
+      #   
+      #   ActiveResource::HttpMock.respond_to(false) do |mock|
+      #     mock.send(:get, "/people/2", {}, "XML2")
+      #   end
+      #   ActiveResource::HttpMock.responses.length #=> 2
+      # 
+      # This also works with passing in generated pairs of requests and responses, again, just pass in false
+      # as the last argument:
+      # 
+      # === Example
+      # 
+      #   ActiveResource::HttpMock.respond_to do |mock|
+      #     mock.send(:get, "/people/1", {}, "XML1")
+      #   end
+      #   ActiveResource::HttpMock.responses.length #=> 1
+      # 
+      #   get_matz         = ActiveResource::Request.new(:get, '/people/1.xml', nil)
+      #   ok_response      = ActiveResource::Response.new("", 200, {})
+      # 
+      #   pairs = {get_matz => ok_response}
+      #
+      #   ActiveResource::HttpMock.respond_to(pairs, false)
+      #   ActiveResource::HttpMock.responses.length #=> 2
+      def respond_to(*args) #:yields: mock
+        pairs = args.first || {}
+        reset! if args.last.class != FalseClass
         responses.concat pairs.to_a
         if block_given?
           yield Responder.new(responses)
diff --git a/activeresource/test/cases/http_mock_test.rb b/activeresource/test/cases/http_mock_test.rb
index a387cd20b1..d90d1e01b8 100644
--- a/activeresource/test/cases/http_mock_test.rb
+++ b/activeresource/test/cases/http_mock_test.rb
@@ -72,6 +72,74 @@ class HttpMockTest < ActiveSupport::TestCase
     
   end
 
+  test "allows you to send in pairs directly to the respond_to method" do
+    matz  = { :id => 1, :name => "Matz" }.to_xml(:root => "person")
+    
+    create_matz = ActiveResource::Request.new(:post, '/people.xml', matz, {})
+    created_response = ActiveResource::Response.new("", 201, {"Location" => "/people/1.xml"})
+    get_matz = ActiveResource::Request.new(:get, '/people/1.xml', nil)
+    ok_response = ActiveResource::Response.new(matz, 200, {})
+    
+    pairs = {create_matz => created_response, get_matz => ok_response}
+    
+    ActiveResource::HttpMock.respond_to(pairs)
+    assert_equal 2, ActiveResource::HttpMock.responses.length
+    assert_equal "", ActiveResource::HttpMock.responses.assoc(create_matz)[1].body
+    assert_equal matz, ActiveResource::HttpMock.responses.assoc(get_matz)[1].body
+  end
+
+  test "resets all mocked responses on each call to respond_to with a block by default" do
+    ActiveResource::HttpMock.respond_to do |mock|
+      mock.send(:get, "/people/1", {}, "XML1")
+    end
+    assert_equal 1, ActiveResource::HttpMock.responses.length
+
+    ActiveResource::HttpMock.respond_to do |mock|
+      mock.send(:get, "/people/2", {}, "XML2")
+    end
+    assert_equal 1, ActiveResource::HttpMock.responses.length
+  end
+
+  test "resets all mocked responses on each call to respond_to by passing pairs by default" do
+    ActiveResource::HttpMock.respond_to do |mock|
+      mock.send(:get, "/people/1", {}, "XML1")
+    end
+    assert_equal 1, ActiveResource::HttpMock.responses.length
+
+    matz  = { :id => 1, :name => "Matz" }.to_xml(:root => "person")
+    get_matz = ActiveResource::Request.new(:get, '/people/1.xml', nil)
+    ok_response = ActiveResource::Response.new(matz, 200, {})
+    ActiveResource::HttpMock.respond_to({get_matz => ok_response})
+
+    assert_equal 1, ActiveResource::HttpMock.responses.length
+  end
+
+  test "allows you to add new responses to the existing responses by calling a block" do
+    ActiveResource::HttpMock.respond_to do |mock|
+      mock.send(:get, "/people/1", {}, "XML1")
+    end
+    assert_equal 1, ActiveResource::HttpMock.responses.length
+
+    ActiveResource::HttpMock.respond_to(false) do |mock|
+      mock.send(:get, "/people/2", {}, "XML2")
+    end
+    assert_equal 2, ActiveResource::HttpMock.responses.length
+  end
+
+  test "allows you to add new responses to the existing responses by passing pairs" do
+    ActiveResource::HttpMock.respond_to do |mock|
+      mock.send(:get, "/people/1", {}, "XML1")
+    end
+    assert_equal 1, ActiveResource::HttpMock.responses.length
+
+    matz  = { :id => 1, :name => "Matz" }.to_xml(:root => "person")
+    get_matz = ActiveResource::Request.new(:get, '/people/1.xml', nil)
+    ok_response = ActiveResource::Response.new(matz, 200, {})
+    ActiveResource::HttpMock.respond_to({get_matz => ok_response}, false)
+
+    assert_equal 2, ActiveResource::HttpMock.responses.length
+  end
+
   def request(method, path, headers = {}, body = nil)
     if [:put, :post].include? method
       @http.send(method, path, body, headers)
diff --git a/activesupport/CHANGELOG b/activesupport/CHANGELOG
index e1904fad39..84cdc22e40 100644
--- a/activesupport/CHANGELOG
+++ b/activesupport/CHANGELOG
@@ -1,14 +1,13 @@
-*Rails 3.0.0 (unreleased)*
-
-* Pluggable cache stores: setting config.cache_store = "custom_store" will require 'active_support/cache/custom_store' and look for the CustomStore constant.  #5486 [Mike Perham]
+*Rails 3.1.0 (unreleased)*
 
+* No changes
 
-*Rails 3.0.0 [release candidate 2] (August 23rd, 2010)*
 
-* No changes
+*Rails 3.0.0 (August 29, 2010)*
 
+* Implemented String#strip_heredoc. [fxn]
 
-*Rails 3.0.0 [release candidate] (July 26th, 2010)*
+* Pluggable cache stores: setting config.cache_store = "custom_store" will require 'active_support/cache/custom_store' and look for the CustomStore constant.  #5486 [Mike Perham]
 
 * Removed Object#returning, Object#tap should be used instead. [Santiago Pastorino]
 
@@ -28,9 +27,6 @@
 
 * Date#since, #ago, #beginning_of_day, #end_of_day, and #xmlschema honor now the user time zone if set. [Geoff Buesing]
 
-
-*Rails 3.0.0 [beta 4] (June 8th, 2010)*
-
 * Extracted String#truncate from TextHelper#truncate [DHH]
 
 * Ruby 1.9: support UTF-8 case folding.  #4595 [Norman Clarke]
@@ -83,18 +79,12 @@
 
 * JSON: encode objects that don't have a native JSON representation using to_hash, if available, instead of instance_values (the old fallback) or to_s (other encoders' default). Encode BigDecimal and Regexp encode as strings to conform with other encoders. Try to transcode non-UTF-8 strings.  [Jeremy Kemper]
 
-
-*Rails 3.0.0 [beta 3] (April 13th, 2010)*
-
 * HashWithIndifferentAccess: remove inherited symbolize_keys! since its keys are always strings.  [Santiago Pastorino]
 
 * Improve transliteration quality.  #4374 [Norman Clarke]
 
 * Speed up and add Ruby 1.9 support for ActiveSupport::Multibyte::Chars#tidy_bytes.  #4350 [Norman Clarke]
 
-
-*Rails 3.0.0 [beta 2] (April 1st, 2010)*
-
 * Reduced load time by deferring configuration of classes using
   ActiveSupport::on_load(:component_name) [YK]
 
@@ -106,9 +96,6 @@
 
 * JSON backend for YAJL. Preferred if available.  #2666 [Brian Lopez]
 
-
-*Rails 3.0.0 [beta 1] (February 4, 2010)*
-
 * Introduce class_attribute to declare inheritable class attributes. Writing an attribute on a subclass behaves just like overriding the superclass reader method.  Unifies and replaces most usage of cattr_accessor, class_inheritable_attribute, superclass_delegating_attribute, and extlib_inheritable_attribute.  [Jeremy Kemper, Yehuda Katz]
 
 * Time#- with a DateTime argument behaves the same as with a Time argument, i.e. returns the difference between self and arg as a Float #3476 [Geoff Buesing]
diff --git a/activesupport/lib/active_support/core_ext/string.rb b/activesupport/lib/active_support/core_ext/string.rb
index d8d1f9436e..8fb8c31ade 100644
--- a/activesupport/lib/active_support/core_ext/string.rb
+++ b/activesupport/lib/active_support/core_ext/string.rb
@@ -9,4 +9,5 @@ require 'active_support/core_ext/string/behavior'
 require 'active_support/core_ext/string/interpolation'
 require 'active_support/core_ext/string/output_safety'
 require 'active_support/core_ext/string/exclude'
-require 'active_support/core_ext/string/encoding'
\ No newline at end of file
+require 'active_support/core_ext/string/encoding'
+require 'active_support/core_ext/string/strip'
diff --git a/activesupport/lib/active_support/core_ext/string/strip.rb b/activesupport/lib/active_support/core_ext/string/strip.rb
new file mode 100644
index 0000000000..086c610976
--- /dev/null
+++ b/activesupport/lib/active_support/core_ext/string/strip.rb
@@ -0,0 +1,26 @@
+require 'active_support/core_ext/object/try'
+
+class String
+  # Strips indentation in heredocs.
+  #
+  # For example in
+  #
+  #   if options[:usage]
+  #     puts <<-USAGE.strip_heredoc
+  #       This command does such and such.
+  #
+  #       Supported options are:
+  #         -h         This message
+  #         ...
+  #     USAGE
+  #   end
+  #
+  # the user would see the usage message aligned against the left margin.
+  #
+  # Technically, it looks for the least indented line in the whole string, and removes
+  # that amount of leading whitespace.
+  def strip_heredoc
+    indent = scan(/^[ \t]*(?=\S)/).min.try(:size) || 0
+    gsub(/^[ \t]{#{indent}}/, '')
+  end
+end
diff --git a/activesupport/test/core_ext/string_ext_test.rb b/activesupport/test/core_ext/string_ext_test.rb
index f7e2ecd357..8be65c99f2 100644
--- a/activesupport/test/core_ext/string_ext_test.rb
+++ b/activesupport/test/core_ext/string_ext_test.rb
@@ -6,10 +6,42 @@ require 'inflector_test_cases'
 require 'active_support/core_ext/string'
 require 'active_support/time'
 require 'active_support/core_ext/kernel/reporting'
+require 'active_support/core_ext/string/strip'
 
 class StringInflectionsTest < Test::Unit::TestCase
   include InflectorTestCases
 
+  def test_strip_heredoc_on_an_empty_string
+    assert_equal '', ''.strip_heredoc
+  end
+
+  def test_strip_heredoc_on_a_string_with_no_lines
+    assert_equal 'x', 'x'.strip_heredoc
+    assert_equal 'x', '    x'.strip_heredoc
+  end
+
+  def test_strip_heredoc_on_a_heredoc_with_no_margin
+    assert_equal "foo\nbar", "foo\nbar".strip_heredoc
+    assert_equal "foo\n  bar", "foo\n  bar".strip_heredoc
+  end
+
+  def test_strip_heredoc_on_a_regular_indented_heredoc
+    assert_equal "foo\n  bar\nbaz\n", <<-EOS.strip_heredoc
+      foo
+        bar
+      baz
+    EOS
+  end
+
+  def test_strip_heredoc_on_a_regular_indented_heredoc_with_blank_lines
+    assert_equal "foo\n  bar\n\nbaz\n", <<-EOS.strip_heredoc
+      foo
+        bar
+
+      baz
+    EOS
+  end
+
   def test_pluralize
     SingularToPlural.each do |singular, plural|
       assert_equal(plural, singular.pluralize)
diff --git a/railties/CHANGELOG b/railties/CHANGELOG
index 046b555a89..6add449cc4 100644
--- a/railties/CHANGELOG
+++ b/railties/CHANGELOG
@@ -1,14 +1,9 @@
-*Rails 3.0.0 (unreleased)*
+*Rails 3.1.0 (unreleased)*
 
 * No changes
 
 
-*Rails 3.0.0 [release candidate 2] (August 23rd, 2010)*
-
-* No changes
-
-
-*Rails 3.0.0 [release candidate] (July 26th, 2010)*
+*Rails 3.0.0 (August 29, 2010)*
 
 * Application generation: --skip-testunit and --skip-activerecord become --skip-test-unit and --skip-active-record respectively. [fxn]
 
@@ -24,19 +19,10 @@
 
 * Made the rails command work even when you're in a subdirectory [Chad Fowler]
 
-
-*Rails 3.0.0 [beta 4] (June 8th, 2010)*
-
 * Removed Rails Metal [Yehuda Katz, José Valim].
 
-
-*Rails 3.0.0 [beta 3] (April 13th, 2010)*
-
 * Renamed config.cookie_secret to config.secret_token and pass it as env key. [José Valim]
 
-
-*Rails 3.0.0 [beta 2] (April 1st, 2010)*
-
 * Session store configuration has changed [Yehuda Katz, Carl Lerche]
 
     config.session_store :cookie_store, {:key => "..."}
@@ -48,8 +34,6 @@
 * Added config.generators.templates to provide alternative paths for the generators
   to look for templates [José Valim]
 
-*Rails 3.0.0 [beta 1] (February 4, 2010)*
-
 * Added "rake about" as a replacement for script/about [DHH]
 
 * Removed all the default commands in script/* and replaced them with script/rails and a rails command that'll act the same when run from within the app [DHH]. Example:
diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index 696db30efb..dfc4d38112 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/railties/guides/source/active_support_core_extensions.textile
@@ -1296,6 +1296,31 @@ Active Support defines 3rd person aliases of +String#start_with?+ and +String#en
 
 NOTE: Defined in +active_support/core_ext/string/starts_ends_with.rb+.
 
+h4. +strip_heredoc+
+
+The method +strip_heredoc+ strips indentation in heredocs.
+
+For example in
+
+<ruby>
+if options[:usage]
+  puts <<-USAGE.strip_heredoc
+    This command does such and such.
+
+    Supported options are:
+      -h         This message
+      ...
+  USAGE
+end
+</ruby>
+
+the user would see the usage message aligned against the left margin.
+
+Technically, it looks for the least indented line in the whole string, and removes
+that amount of leading whitespace.
+
+NOTE: Defined in +active_support/core_ext/string/strip.rb+.
+
 h4. Access
 
 h5. +at(position)+
diff --git a/railties/guides/source/contributing_to_rails.textile b/railties/guides/source/contributing_to_rails.textile
index a0225b4b17..7184759610 100644
--- a/railties/guides/source/contributing_to_rails.textile
+++ b/railties/guides/source/contributing_to_rails.textile
@@ -69,7 +69,7 @@ All of the Rails tests must pass with any code you submit, otherwise you have no
 NOTE: Ensure you install bundler v1.0
 
 <shell>
-gem install -v=1.0.0 bundler
+gem install bundler
 bundle install --without db
 </shell>