11 files changed, 82 insertions, 56 deletions
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 6a91418e1f..f1600fe458 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -410,7 +410,7 @@ class ApplicationController < ActionController::Base
   # logging out removes it.
   def current_user
     @_current_user ||= session[:current_user_id] &&
-      User.find_by_id(session[:current_user_id])
+      User.find_by(id: session[:current_user_id])
   end
 end
 ```
diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md
index d1dd231cf6..87a08e8661 100644
--- a/guides/source/action_mailer_basics.md
+++ b/guides/source/action_mailer_basics.md
@@ -216,6 +216,11 @@ Action Mailer makes it very easy to add attachments.
     attachments['filename.jpg'] = File.read('/path/to/filename.jpg')
     ```
 
+  When the `mail` method will be triggered, it will send a multipart email with
+  an attachment, properly nested with the top level being `multipart/mixed` and
+  the first part being a `multipart/alternative` containing the plain text and
+  HTML email messages.
+
 NOTE: Mail will automatically Base64 encode an attachment. If you want something
 different, encode your content and pass in the encoded content and encoding in a
 `Hash` to the `attachments` method.
@@ -451,26 +456,6 @@ with the HTML and text versions setup as different parts.
 The order of the parts getting inserted is determined by the `:parts_order`
 inside of the `ActionMailer::Base.default` method.
 
-### Sending Emails with Attachments
-
-Attachments can be added by using the `attachments` method:
-
-```ruby
-class UserMailer < ActionMailer::Base
-  def welcome_email(user)
-    @user = user
-    @url  = user_url(@user)
-    attachments['terms.pdf'] = File.read('/path/terms.pdf')
-    mail(to: @user.email,
-         subject: 'Please see the Terms and Conditions attached')
-  end
-end
-```
-
-The above will send a multipart email with an attachment, properly nested with
-the top level being `multipart/mixed` and the first part being a
-`multipart/alternative` containing the plain text and HTML email messages.
-
 ### Sending Emails with Dynamic Delivery Options
 
 If you wish to override the default delivery options (e.g. SMTP credentials)
@@ -532,7 +517,7 @@ method. Here's an example:
 ```ruby
 class UserMailer < ActionMailer::Base
   def receive(email)
-    page = Page.find_by_address(email.to.first)
+    page = Page.find_by(address: email.to.first)
     page.emails.create(
       subject: email.subject,
       body: email.body
diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md
index 1f25c6ae95..d9fb20f3bf 100644
--- a/guides/source/active_record_basics.md
+++ b/guides/source/active_record_basics.md
@@ -253,7 +253,7 @@ user = User.first
 
 ```ruby
 # return the first user named David
-david = User.find_by_name('David')
+david = User.find_by(name: 'David')
 ```
 
 ```ruby
@@ -270,7 +270,7 @@ Once an Active Record object has been retrieved, its attributes can be modified
 and it can be saved to the database.
 
 ```ruby
-user = User.find_by_name('David')
+user = User.find_by(name: 'David')
 user.name = 'Dave'
 user.save
 ```
@@ -279,7 +279,7 @@ A shorthand for this is to use a hash mapping attribute names to the desired
 value, like so:
 
 ```ruby
-user = User.find_by_name('David')
+user = User.find_by(name: 'David')
 user.update(name: 'Dave')
 ```
 
@@ -297,7 +297,7 @@ Likewise, once retrieved an Active Record object can be destroyed which removes
 it from the database.
 
 ```ruby
-user = User.find_by_name('David')
+user = User.find_by(name: 'David')
 user.destroy
 ```
 
diff --git a/guides/source/active_record_callbacks.md b/guides/source/active_record_callbacks.md
index bb42fab101..01401cc340 100644
--- a/guides/source/active_record_callbacks.md
+++ b/guides/source/active_record_callbacks.md
@@ -167,6 +167,7 @@ Additionally, the `after_find` callback is triggered by the following finder met
 * `all`
 * `first`
 * `find`
+* `find_by`
 * `find_by_*`
 * `find_by_*!`
 * `find_by_sql`
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index c0e584a1c7..884aa6a9ea 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -2171,7 +2171,7 @@ You're not limited to the functionality that Rails automatically builds into ass
 class Customer < ActiveRecord::Base
   has_many :orders do
     def find_by_order_prefix(order_number)
-      find_by_region_id(order_number[0..2])
+      find_by(region_id: order_number[0..2])
     end
   end
 end
diff --git a/guides/source/debugging_rails_applications.md b/guides/source/debugging_rails_applications.md
index 0860e3119d..c17aa64cac 100644
--- a/guides/source/debugging_rails_applications.md
+++ b/guides/source/debugging_rails_applications.md
@@ -661,6 +661,8 @@ There are some Rails plugins to help you to find errors and debug your applicati
 * [Query Trace](https://github.com/ntalbott/query_trace/tree/master) Adds query origin tracing to your logs.
 * [Query Reviewer](https://github.com/nesquena/query_reviewer) This rails plugin not only runs "EXPLAIN" before each of your select queries in development, but provides a small DIV in the rendered output of each page with the summary of warnings for each query that it analyzed.
 * [Exception Notifier](https://github.com/smartinez87/exception_notification/tree/master) Provides a mailer object and a default set of templates for sending email notifications when errors occur in a Rails application.
+* [Better Errors](https://github.com/charliesome/better_errors) Replaces the standard Rails error page with a new one containing more contextual information, like source code and variable inspection.
+* [RailsPanel](https://github.com/dejan/rails_panel) Chrome extension for Rails development that will end your tailing of development.log. Have all information about your Rails app requests in the browser - in the Developer Tools panel. Provides insight to db/rendering/total times, parameter list, rendered views and more.
 
 References
 ----------
diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md
index e6c610e817..26360e815b 100644
--- a/guides/source/getting_started.md
+++ b/guides/source/getting_started.md
@@ -252,8 +252,8 @@ Now that you've seen how to create a controller, an action and a view, let's cre
 
 In the Blog application, you will now create a new _resource_. A resource is the term used for a collection of similar objects, such as posts, people or animals. You can create, read, update and destroy items for a resource and these operations are referred to as _CRUD_ operations.
 
-Rails provides a `resources` method which can be used to declare a
-standard REST resource. Here's how `config/routes.rb` will look like.
+Rails provides a `resources` method which can be used to declare a standard REST resource.
+Here's what `config/routes.rb` should look like after the _post resource_ is declared.
 
 ```ruby
 Blog::Application.routes.draw do
@@ -612,11 +612,16 @@ we want to accept in our controllers. In this case, we want to allow the
 look like this:
 
 ```
-  def create
-    @post = Post.new(params[:post].permit(:title, :text))
+def create
+  @post = Post.new(post_params)
 
-    @post.save
-    redirect_to @post
+  @post.save
+  redirect_to @post
+end
+
+private
+  def post_params
+    params.require(:post).permit(:title, :text)
   end
 ```
 
@@ -767,7 +772,7 @@ def new
 end
 
 def create
-  @post = Post.new(params[:post].permit(:title, :text))
+  @post = Post.new(post_params)
 
   if @post.save
     redirect_to @post
@@ -775,6 +780,11 @@ def create
     render 'new'
   end
 end
+
+private
+  def post_params
+    params.require(:post).permit(:title, :text)
+  end
 ```
 
 The `new` action is now creating a new instance variable called `@post`, and
@@ -905,12 +915,17 @@ Next we need to create the `update` action in `app/controllers/posts_controller.
 def update
   @post = Post.find(params[:id])
 
-  if @post.update(params[:post].permit(:title, :text))
+  if @post.update(post_params)
     redirect_to @post
   else
     render 'edit'
   end
 end
+
+private
+  def post_params
+    params.require(:post).permit(:title, :text)
+  end
 ```
 
 The new method, `update`, is used when you want to update a record
@@ -918,6 +933,8 @@ that already exists, and it accepts a hash containing the attributes
 that you want to update. As before, if there was an error updating the
 post we want to show the form back to the user.
 
+We reuse the `post_params` method that we defined earlier for the create action.
+
 TIP: You don't need to pass all attributes to `update`. For
 example, if you'd call `@post.update(title: 'A new title')`
 Rails would only update the `title` attribute, leaving all other
@@ -1062,7 +1079,7 @@ You can call `destroy` on Active Record objects when you want to delete
 them from the database. Note that we don't need to add a view for this
 action since we're redirecting to the `index` action.
 
-Finally, add a 'destroy' link to your `index` action template
+Finally, add a 'Destroy' link to your `index` action template
 (`app/views/posts/index.html.erb`) to wrap everything
 together.
 
@@ -1088,8 +1105,8 @@ together.
 </table>
 ```
 
-Here we're using `link_to` in a different way. We pass the named route as the first argument,
-and then the final two keys as another argument. The `:method` and `:'data-confirm'`
+Here we're using `link_to` in a different way. We pass the named route as the second argument,
+and then the options as another argument. The `:method` and `:'data-confirm'`
 options are used as HTML5 attributes so that when the link is clicked,
 Rails will first show a confirm dialog to the user, and then submit the link with method `delete`.
 This is done via the JavaScript file `jquery_ujs` which is automatically included
@@ -1303,9 +1320,14 @@ Let's wire up the `create` in `app/controllers/comments_controller.rb`:
 class CommentsController < ApplicationController
   def create
     @post = Post.find(params[:post_id])
-    @comment = @post.comments.create(params[:comment].permit(:commenter, :body))
+    @comment = @post.comments.create(comment_params)
     redirect_to post_path(@post)
   end
+
+  private
+    def comment_params
+      params.require(:comment).permit(:commenter, :body)
+    end
 end
 ```
 
@@ -1527,10 +1549,9 @@ controller (`app/controllers/comments_controller.rb`):
 
 ```ruby
 class CommentsController < ApplicationController
-
   def create
     @post = Post.find(params[:post_id])
-    @comment = @post.comments.create(params[:comment])
+    @comment = @post.comments.create(comment_params)
     redirect_to post_path(@post)
   end
 
@@ -1541,6 +1562,10 @@ class CommentsController < ApplicationController
     redirect_to post_path(@post)
   end
 
+  private
+    def comment_params
+      params.require(:comment).permit(:commenter, :body)
+    end
 end
 ```
 
diff --git a/guides/source/initialization.md b/guides/source/initialization.md
index 738591659d..11c736585f 100644
--- a/guides/source/initialization.md
+++ b/guides/source/initialization.md
@@ -7,14 +7,17 @@ as of Rails 4. It is an extremely in-depth guide and recommended for advanced Ra
 After reading this guide, you will know:
 
 * How to use `rails server`.
+* The timeline of Rails' initialization sequence.
+* Where different files are required by the boot sequence.
+* How the Rails::Server interface is defined and used.
 
 --------------------------------------------------------------------------------
 
 This guide goes through every 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 what happens when you execute +rails
-server+ to boot your app.
+guide, we will be focusing on what happens when you execute `rails server`
+to boot your app.
 
 NOTE: Paths in this guide are relative to Rails or a Rails application unless otherwise specified.
 
@@ -26,7 +29,7 @@ quickly.
 Launch!
 -------
 
-Now we finally boot and initialize the app. It all starts with your app's
+Let's start to boot and initialize the app. It all begins with your app's
 `bin/rails` executable. A Rails application is usually started by running
 `rails console` or `rails server`.
 
@@ -57,7 +60,8 @@ require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])
 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.
+exists, then `bundler/setup` is required. The require is used by Bundler to
+configure the load path for your Gemfile's dependencies.
 
 A standard Rails application depends on several gems, specifically:
 
@@ -251,9 +255,9 @@ set earlier) is required.
 
 ### `config/application`
 
-When `require APP_PATH` is executed, `config/application.rb` is loaded.
-This file exists in your app and it's free for you to change based
-on your needs.
+When `require APP_PATH` is executed, `config/application.rb` is loaded (recall
+that `APP_PATH` is defined in `bin/rails`). This file exists in your application
+and it's free for you to change based on your needs.
 
 ### `Rails::Server#start`
 
@@ -443,7 +447,9 @@ I18n and Rails configuration are all being defined here.
 
 ### Back to `config/environment.rb`
 
-When `config/application.rb` has finished loading Rails, and defined
+The rest of `config/application.rb` defines the configuration for the
+`Rails::Application` which will be used once the application is fully 
+initialized. When `config/application.rb` has finished loading Rails and defined
 the application namespace, we go back to `config/environment.rb`,
 where the application is initialized. For example, if the application was called
 `Blog`, here we would find `Blog::Application.initialize!`, which is
@@ -471,6 +477,13 @@ traverses all the class ancestors looking for an `initializers` method,
 sorting them and running them. For example, the `Engine` class will make
 all the engines available by providing the `initializers` method.
 
+The `Rails::Application` class, as defined in `railties/lib/rails/application.rb`
+defines `bootstrap`, `railtie`, and `finisher` initializers. The `bootstrap` initializers
+prepare the application (like initializing the logger) while the `finisher`
+initializers (like building the middleware stack) are run last. The `railtie`
+initializers are the initializers which have been defined on the `Rails::Application`
+itself and are run between the `bootstrap` and `finishers`.
+
 After this is done we go back to `Rack::Server`
 
 ### Rack: lib/rack/server.rb
diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md
index 1ab841b137..5908801bc9 100644
--- a/guides/source/layouts_and_rendering.md
+++ b/guides/source/layouts_and_rendering.md
@@ -592,7 +592,7 @@ def index
 end
 
 def show
-  @book = Book.find_by_id(params[:id])
+  @book = Book.find_by(id: params[:id])
   if @book.nil?
     render action: "index"
   end
@@ -607,7 +607,7 @@ def index
 end
 
 def show
-  @book = Book.find_by_id(params[:id])
+  @book = Book.find_by(id: params[:id])
   if @book.nil?
     redirect_to action: :index
   end
@@ -626,10 +626,10 @@ def index
 end
 
 def show
-  @book = Book.find_by_id(params[:id])
+  @book = Book.find_by(id: params[:id])
   if @book.nil?
     @books = Book.all
-    flash[:alert] = "Your book was not found"
+    flash.now[:alert] = "Your book was not found"
     render "index"
   end
 end
diff --git a/guides/source/migrations.md b/guides/source/migrations.md
index 508e52a77c..035f9499de 100644
--- a/guides/source/migrations.md
+++ b/guides/source/migrations.md
@@ -314,7 +314,7 @@ will produce a migration that looks like this
 class AddDetailsToProducts < ActiveRecord::Migration
   def change
     add_column :products, :price, precision: 5, scale: 2
-    add_reference :products, :user, polymorphic: true, index: true
+    add_reference :products, :supplier, polymorphic: true, index: true
   end
 end
 ```
diff --git a/guides/source/testing.md b/guides/source/testing.md
index 416a8b592f..62c9835fa4 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -92,7 +92,7 @@ user_<%= n %>:
 
 #### Fixtures in Action
 
-Rails by default automatically loads all fixtures from the `test/fixtures` folder for your unit and functional test. Loading involves three steps:
+Rails by default automatically loads all fixtures from the `test/fixtures` folder for your models and controllers test. Loading involves three steps:
 
 * Remove any existing data from the table corresponding to the fixture
 * Load the fixture data into the table
@@ -116,7 +116,7 @@ email(david.girlfriend.email, david.location_tonight)
 Unit Testing your Models
 ------------------------
 
-In Rails, unit tests are what you write to test your models.
+In Rails, models tests are what you write to test your models.
 
 For this guide we will be using Rails _scaffolding_. It will create the model, a migration, controller and views for the new resource in a single operation. It will also create a full test suite following Rails best practices. I will be using examples from this generated code and will be supplementing it with additional examples where necessary.