7 files changed, 199 insertions, 43 deletions
diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile
index 80faffa49c..587f65529e 100644
--- a/guides/source/active_support_core_extensions.textile
+++ b/guides/source/active_support_core_extensions.textile
@@ -2549,6 +2549,45 @@ There's also the bang variant +except!+ that removes keys in the very receiver.
 
 NOTE: Defined in +active_support/core_ext/hash/except.rb+.
 
+h5. +transform_keys+ and +transform_keys!+
+
+The method +transform_keys+ accepts a block and returns a hash that has applied the block operations to each of the keys in the receiver:
+
+<ruby>
+{nil => nil, 1 => 1, :a => :a}.transform_keys{ |key| key.to_s.upcase }
+# => {"" => nil, "A" => :a, "1" => 1}
+</ruby>
+
+The result in case of collision is undefined:
+
+<ruby>
+{"a" => 1, :a => 2}.transform_keys{ |key| key.to_s.upcase }
+# => {"A" => 2}, in my test, can't rely on this result though
+</ruby>
+
+This method may be useful for example to build specialized conversions. For instance +stringify_keys+ and +symbolize_keys+ use +transform_keys+ to perform their key conversions:
+
+<ruby>
+def stringify_keys
+  transform_keys{ |key| key.to_s }
+end
+...
+def symbolize_keys
+  transform_keys{ |key| key.to_sym rescue key }
+end
+</ruby>
+
+There's also the bang variant +transform_keys!+ that applies the block operations to keys in the very receiver.
+
+Besides that, one can use +deep_transform_keys+ and +deep_transform_keys!+ to perform the block operation on all the keys in the given hash and all the hashes nested into it. An example of the result is:
+
+<ruby>
+{nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_transform_keys{ |key| key.to_s.upcase }
+# => {""=>nil, "1"=>1, "NESTED"=>{"A"=>3, "5"=>5}}
+</ruby>
+
+NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
+
 h5. +stringify_keys+ and +stringify_keys!+
 
 The method +stringify_keys+ returns a hash that has a stringified version of the keys in the receiver. It does so by sending +to_s+ to them:
@@ -2579,6 +2618,13 @@ The second line can safely access the "type" key, and let the user to pass eithe
 
 There's also the bang variant +stringify_keys!+ that stringifies keys in the very receiver.
 
+Besides that, one can use +deep_stringify_keys+ and +deep_stringify_keys!+ to stringify all the keys in the given hash and all the hashes nested into it. An example of the result is:
+
+<ruby>
+{nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_stringify_keys
+# => {""=>nil, "1"=>1, "nested"=>{"a"=>3, "5"=>5}}
+</ruby>
+
 NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
 
 h5. +symbolize_keys+ and +symbolize_keys!+
@@ -2613,6 +2659,13 @@ The second line can safely access the +:params+ key, and let the user to pass ei
 
 There's also the bang variant +symbolize_keys!+ that symbolizes keys in the very receiver.
 
+Besides that, one can use +deep_symbolize_keys+ and +deep_symbolize_keys!+ to symbolize all the keys in the given hash and all the hashes nested into it. An example of the result is:
+
+<ruby>
+{nil => nil, 1 => 1, "nested" => {"a" => 3, 5 => 5}}.deep_symbolize_keys
+# => {nil=>nil, 1=>1, :nested=>{:a=>3, 5=>5}}
+</ruby>
+
 NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
 
 h5. +to_options+ and +to_options!+
diff --git a/guides/source/configuring.textile b/guides/source/configuring.textile
index f114075cae..af46538bf5 100644
--- a/guides/source/configuring.textile
+++ b/guides/source/configuring.textile
@@ -585,7 +585,7 @@ After loading the framework and any gems in your application, Rails turns to loa
 
 NOTE: You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the initializers folder on down.
 
-TIP: If you have any ordering dependency in your initializers, you can control the load order by naming. For example, +01_critical.rb+ will be loaded before +02_normal.rb+.
+TIP: If you have any ordering dependency in your initializers, you can control the load order through naming. Initializer files are loaded in alphabetical order by their path. For example, +01_critical.rb+ will be loaded before +02_normal.rb+.
 
 h3. Initialization events
 
diff --git a/guides/source/contributing_to_ruby_on_rails.textile b/guides/source/contributing_to_ruby_on_rails.textile
index a2254a550c..72cdea885f 100644
--- a/guides/source/contributing_to_ruby_on_rails.textile
+++ b/guides/source/contributing_to_ruby_on_rails.textile
@@ -430,6 +430,35 @@ h4. Iterate as Necessary
 
 It’s entirely possible that the feedback you get will suggest changes. Don’t get discouraged: the whole point of contributing to an active open source project is to tap into community knowledge. If people are encouraging you to tweak your code, then it’s worth making the tweaks and resubmitting. If the feedback is that your code doesn’t belong in the core, you might still think about releasing it as a gem.
 
+h4. Backporting
+
+Changes that are merged into master are intended for the next major release of Rails. Sometimes, it might be beneficial for your changes to propagate back to the maintenance releases for older stable branches. Generally, security fixes and bug fixes are good candidates for a backport, while new features and patches that introduce a change in behavior will not be accepted. When in doubt, it is best to consult a rails team member before backporting your changes to avoid wasted effort.
+
+For simple fixes, the easiest way to backport your change is to "extract a diff from your changes in master and apply them to the target branch":http://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git.
+
+First make sure your changes are the only difference between your current branch and master:
+
+<shell>
+$ git log master..HEAD
+</shell>
+
+Then extract the diff:
+
+<shell>
+$ git format-patch master --stdout > ~/my_changes.patch
+</shell>
+
+Switch over to the target branch and apply your changes:
+
+<shell>
+$ git checkout -b my_backport_branch 3-2-stable
+$ git apply ~/my_changes.patch
+</shell>
+
+This works well for simple changes. However, if your changes are complicated or if the code in master has deviated significantly from your target branch, it might require more work on your part. The difficulty of a backport varies greatly from case to case, and sometimes it is simply not worth the effort.
+
+Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the ruby versions listed in +.travis.yml+ before submitting your pull request.
+
 And then ... think about your next contribution!
 
 h3. Rails Contributors
diff --git a/guides/source/credits.html.erb b/guides/source/credits.html.erb
index da6bd6acdf..04deec6a11 100644
--- a/guides/source/credits.html.erb
+++ b/guides/source/credits.html.erb
@@ -31,6 +31,10 @@ Ruby on Rails Guides: Credits
 Ryan Bigg works as a consultant at <a href="http://rubyx.com">RubyX</a> and has been working with Rails since 2006. He's co-authoring a book called <a href="http://manning.com/katz">Rails 3 in Action</a> and he's written many gems which can be seen on <a href="http://github.com/radar">his GitHub page</a> and he also tweets prolifically as <a href="http://twitter.com/ryanbigg">@ryanbigg</a>.
 <% end %>
 
+<%= author('Oscar Del Ben', 'oscardelben', 'oscardelben.jpg') do %>
+Oscar Del Ben is a software engineer at <a href="http://www.wildfireapp.com/">Wildfire</a>. He's a regular open source contributor (<a href="https://github.com/oscardelben">Github account</a>) and tweets regularly at <a href="https://twitter.com/oscardelben">@oscardelben</a>.
+  <% end %>
+
 <%= author('Frederick Cheung', 'fcheung') do %>
   Frederick Cheung is Chief Wizard at Texperts where he has been using Rails since 2006. He is based in Cambridge (UK) and when not consuming fine ales he blogs at <a href="http://www.spacevatican.org">spacevatican.org</a>.
 <% end %>
diff --git a/guides/source/debugging_rails_applications.textile b/guides/source/debugging_rails_applications.textile
index 45fa4ada78..0802a2db26 100644
--- a/guides/source/debugging_rails_applications.textile
+++ b/guides/source/debugging_rails_applications.textile
@@ -698,7 +698,7 @@ There are some Rails plugins to help you to find errors and debug your applicati
 
 h3. References
 
-* "ruby-debug Homepage":http://www.datanoise.com/ruby-debug
+* "ruby-debug Homepage":http://bashdb.sourceforge.net/ruby-debug/home-page.html
 * "debugger Homepage":http://github.com/cldwalker/debugger
 * "Article: Debugging a Rails application with ruby-debug":http://www.sitepoint.com/article/debug-rails-app-ruby-debug/
 * "ruby-debug Basics screencast":http://brian.maybeyoureinsane.net/blog/2007/05/07/ruby-debug-basics-screencast/
diff --git a/guides/source/getting_started.textile b/guides/source/getting_started.textile
index e25dac22da..1799d55a7a 100644
--- a/guides/source/getting_started.textile
+++ b/guides/source/getting_started.textile
@@ -13,8 +13,6 @@ endprologue.
 WARNING. This Guide is based on Rails 3.2. Some of the code shown here will not
 work in earlier versions of Rails.
 
-WARNING: The Edge version of this guide is currently being re-worked. Please excuse us while we re-arrange the place.
-
 h3. Guide Assumptions
 
 This guide is designed for beginners who want to get started with a Rails
@@ -179,7 +177,28 @@ To create a new controller, you will need to run the "controller" generator and
 $ rails generate controller welcome index
 </shell>
 
-Rails will create several files for you. Most important of these are of course the controller, located at +app/controllers/welcome_controller.rb+ and the view, located at +app/views/welcome/index.html.erb+.
+Rails will create several files and a route for you.
+
+<shell>
+create  app/controllers/welcome_controller.rb
+ route  get "welcome/index"
+invoke  erb
+create    app/views/welcome
+create    app/views/welcome/index.html.erb
+invoke  test_unit
+create    test/functional/welcome_controller_test.rb
+invoke  helper
+create    app/helpers/welcome_helper.rb
+invoke    test_unit
+create      test/unit/helpers/welcome_helper_test.rb
+invoke  assets
+invoke    coffee
+create      app/assets/javascripts/welcome.js.coffee
+invoke    scss
+create      app/assets/stylesheets/welcome.css.scss
+</shell>
+
+Most important of these are of course the controller, located at +app/controllers/welcome_controller.rb+ and the view, located at +app/views/welcome/index.html.erb+.
 
 Open the +app/views/welcome/index.html.erb+ file in your text editor and edit it to contain a single line of code:
 
@@ -197,18 +216,27 @@ You need to do this because Rails will serve any static file in the +public+ dir
 
 Next, you have to tell Rails where your actual home page is located.
 
-Open the file +config/routes.rb+ in your editor. This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with +root :to+ and uncomment it. It should look something like the following:
+Open the file +config/routes.rb+ in your editor. 
 
 <ruby>
 Blog::Application.routes.draw do
-
-  #...
+  get "welcome/index"
+  
+  # The priority is based upon order of creation:
+  # first created -> highest priority.
+  # ...
   # You can have the root of your site routed with "root"
   # just remember to delete public/index.html.
-  root :to => "welcome#index"
+  # root :to => "welcome#index"
+</ruby>
+
+This is your application's _routing file_ which holds entries in a special DSL (domain-specific language) that tells Rails how to connect incoming requests to controllers and actions. This file contains many sample routes on commented lines, and one of them actually shows you how to connect the root of your site to a specific controller and action. Find the line beginning with +root :to+ and uncomment it. It should look something like the following:
+
+<ruby>
+root :to => "welcome#index"
 </ruby>
 
-The +root :to => "welcome#index"+ tells Rails to map requests to the root of the application to the welcome controller's index action. This was created earlier when you ran the controller generator (+rails generate controller welcome index+).
+The +root :to => "welcome#index"+ tells Rails to map requests to the root of the application to the welcome controller's index action and +get "welcome/index"+ tells Rails to map requests to "http://localhost:3000/welcome/index":http://localhost:3000/welcome/index to the welcome controller's index action. This was created earlier when you ran the controller generator (+rails generate controller welcome index+).
 
 If you navigate to "http://localhost:3000":http://localhost:3000 in your browser, you'll see the +Hello, Rails!+ message you put into +app/views/welcome/index.html.erb+, indicating that this new route is indeed going to +WelcomeController+'s +index+ action and is rendering the view correctly.
 
diff --git a/guides/source/initialization.textile b/guides/source/initialization.textile
index 155a439e64..12b2eb7458 100644
--- a/guides/source/initialization.textile
+++ b/guides/source/initialization.textile
@@ -1,13 +1,15 @@
 h2. The Rails Initialization Process
 
-This guide explains the internals of the initialization process in Rails as of Rails 3.1. It is an extremely in-depth guide and recommended for advanced Rails developers.
+This guide explains the internals of the initialization process in Rails
+as of Rails 4. It is an extremely in-depth guide and recommended for advanced Rails developers.
 
 * Using +rails server+
 * Using Passenger
 
 endprologue.
 
-This guide goes through every single file, class and method call that is required to boot up the Ruby on Rails stack for a default Rails 3.1 application, explaining each part in detail along the way. For this guide, we will be focusing on how the two most common methods (+rails server+ and Passenger) boot a Rails application.
+This guide goes through every single file, class and method call that is
+required to boot up the Ruby on Rails stack for a default Rails 4 application, explaining each part in detail along the way. For this guide, we will be focusing on how the two most common methods (+rails server+ and Passenger) boot a Rails application.
 
 NOTE: Paths in this guide are relative to Rails or a Rails application unless otherwise specified.
 
@@ -22,16 +24,15 @@ The actual +rails+ command is kept in _bin/rails_:
 <ruby>
 #!/usr/bin/env ruby
 
-begin
-  require "rails/cli"
-rescue LoadError
-  railties_path = File.expand_path('../../railties/lib', __FILE__)
+if File.exists?(File.join(File.expand_path('../../..', __FILE__), '.git'))
+  railties_path = File.expand_path('../../lib', __FILE__)
   $:.unshift(railties_path)
-  require "rails/cli"
 end
+require "rails/cli"
 </ruby>
 
-This file will attempt to load +rails/cli+. If it cannot find it then +railties/lib+ is added to the load path (+$:+) before retrying.
+This file will first attempt to push the +railties/lib+ directory if
+present, and then require +rails/cli+.
 
 h4. +railties/lib/rails/cli.rb+
 
@@ -46,7 +47,7 @@ require 'rails/script_rails_loader'
 Rails::ScriptRailsLoader.exec_script_rails!
 
 require 'rails/ruby_version_check'
-Signal.trap("INT") { puts; exit }
+Signal.trap("INT") { puts; exit(1) }
 
 if ARGV.first == 'plugin'
   ARGV.shift
@@ -56,7 +57,7 @@ else
 end
 </ruby>
 
-The +rbconfig+ file from the Ruby standard library provides us with the +RbConfig+ class which contains detailed information about the Ruby environment, including how Ruby was compiled. We can see this in use in +railties/lib/rails/script_rails_loader+.
+The +rbconfig+ file from the Ruby standard library provides us with the +RbConfig+ class which contains detailed information about the Ruby environment, including how Ruby was compiled. We can see thisin use in +railties/lib/rails/script_rails_loader+.
 
 <ruby>
 require 'pathname'
@@ -120,6 +121,9 @@ exec RUBY, SCRIPT_RAILS, *ARGV if in_rails_application?
 
 This is effectively the same as running +ruby script/rails [arguments]+, where +[arguments]+ at this point in time is simply "server".
 
+TIP: If you execute +script/rails+ directly from your Rails app you will
+avoid executing the code that we just described.
+
 h4. +script/rails+
 
 This file is as follows:
@@ -134,23 +138,23 @@ The +APP_PATH+ constant will be used later in +rails/commands+. The +config/boot
 
 h4. +config/boot.rb+
 
-+config/boot.rb+ contains this:
++config/boot.rb+ contains:
 
 <ruby>
 # Set up gems listed in the Gemfile.
-gemfile = File.expand_path('../../Gemfile', __FILE__)
-begin
-  ENV['BUNDLE_GEMFILE'] = gemfile
-  require 'bundler'
-  Bundler.setup
-rescue Bundler::GemNotFound => e
-  STDERR.puts e.message
-  STDERR.puts "Try running `bundle install`."
-  exit!
-end if File.exist?(gemfile)
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
+
+require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])
 </ruby>
 
-In a standard Rails application, there's a +Gemfile+ which declares all dependencies of the application. +config/boot.rb+ sets +ENV["BUNDLE_GEMFILE"]+ to the location of this file, then requires Bundler and calls +Bundler.setup+ which adds the dependencies of the application (including all the Rails parts) to the load path, making them available for the application to load. The gems that a Rails 3.1 application depends on are as follows:
+In a standard Rails application, there's a +Gemfile+ which declares all
+dependencies of the application. +config/boot.rb+ sets
++ENV['BUNDLE_GEMFILE']+ to the location of this file. If the Gemfile
+exists, +bundler/setup+ is then required.
+
+The gems that a Rails 4 application depends on are as follows:
+
+TODO: change these when the Rails 4 release is near.
 
 * abstract (1.0.0)
 * actionmailer (3.1.0.beta)
@@ -183,6 +187,8 @@ h4. +rails/commands.rb+
 Once +config/boot.rb+ has finished, the next file that is required is +rails/commands+ which will execute a command based on the arguments passed in. In this case, the +ARGV+ array simply contains +server+ which is extracted into the +command+ variable using these lines:
 
 <ruby>
+ARGV << '--help' if ARGV.empty?
+
 aliases = {
   "g"  => "generate",
   "c"  => "console",
@@ -195,6 +201,9 @@ command = ARGV.shift
 command = aliases[command] || command
 </ruby>
 
+TIP: As you can see, an empty ARGV list will make Rails show the help
+snippet.
+
 If we used <tt>s</tt> rather than +server+, Rails will use the +aliases+ defined in the file and match them to their respective commands. With the +server+ command, Rails will run this code:
 
 <ruby>
@@ -361,8 +370,9 @@ This method is defined like this:
 
 <ruby>
 def start
+  url = "#{options[:SSLEnable] ? 'https' : 'http'}://#{options[:Host]}:#{options[:Port]}"
   puts "=> Booting #{ActiveSupport::Inflector.demodulize(server)}"
-  puts "=> Rails #{Rails.version} application starting in #{Rails.env} on http://#{options[:Host]}:#{options[:Port]}"
+  puts "=> Rails #{Rails.version} application starting in #{Rails.env} on #{url}"
   puts "=> Call with -d to detach" unless options[:daemonize]
   trap(:INT) { exit }
   puts "=> Ctrl-C to shutdown server" unless options[:daemonize]
@@ -372,6 +382,15 @@ def start
     FileUtils.mkdir_p(Rails.root.join('tmp', dir_to_make))
   end
 
+  unless options[:daemonize]
+    wrapped_app # touch the app so the logger is set up
+
+    console = ActiveSupport::Logger.new($stdout)
+    console.formatter = Rails.logger.formatter
+
+    Rails.logger.extend(ActiveSupport::Logger.broadcast(console))
+  end
+
   super
 ensure
   # The '-h' option calls exit before @options is set.
@@ -380,10 +399,18 @@ ensure
 end
 </ruby>
 
-This is where the first output of the Rails initialization happens. This method creates a trap for +INT+ signals, so if you +CTRL+C+ the server, it will exit the process. As we can see from the code here, it will create the +tmp/cache+, +tmp/pids+, +tmp/sessions+ and +tmp/sockets+ directories if they don't already exist prior to calling +super+. The +super+ method will call +Rack::Server.start+ which begins its definition like this:
+This is where the first output of the Rails initialization happens. This
+method creates a trap for +INT+ signals, so if you +CTRL-C+ the server,
+it will exit the process. As we can see from the code here, it will
+create the +tmp/cache+, +tmp/pids+, +tmp/sessions+ and +tmp/sockets+
+directories. It then calls +wrapped_app+ which is responsible for
+creating the Rack app, before creating and assignig an
+instance of +ActiveSupport::Logger+.
+
+The +super+ method will call +Rack::Server.start+ which begins its definition like this:
 
 <ruby>
-def start
+def start &blk
   if options[:warn]
     $-w = true
   end
@@ -403,22 +430,37 @@ def start
     pp wrapped_app
     pp app
   end
-end
-</ruby>
 
-In a Rails application, these options are not set at all and therefore aren't used at all. The first line of code that's executed in this method is a call to this method:
+  check_pid! if options[:pid]
 
-<ruby>
-wrapped_app
+  # Touch the wrapped app, so that the config.ru is loaded before
+  # daemonization (i.e. before chdir, etc).
+  wrapped_app
+
+  daemonize_app if options[:daemonize]
+
+  write_pid if options[:pid]
+
+  trap(:INT) do
+    if server.respond_to?(:shutdown)
+      server.shutdown
+    else
+      exit
+    end
+  end
+
+  server.run wrapped_app, options, &blk
+end
 </ruby>
 
-This method calls another method:
+The interesting part for a Rails app is the last line, +server.run+. Here we encounter the +wrapped_app+ method again, which this time
+we're going to explore more.
 
 <ruby>
 @wrapped_app ||= build_app app
 </ruby>
 
-Then the +app+ method here is defined like so:
+The +app+ method here is defined like so:
 
 <ruby>
 def app
@@ -440,7 +482,7 @@ The +options[:config]+ value defaults to +config.ru+ which contains this:
 # This file is used by Rack-based servers to start the application.
 
 require ::File.expand_path('../config/environment',  __FILE__)
-run YourApp::Application
+run <%= app_const %>
 </ruby>