rails 4.0.0 → 4.2.11.3

data/guides/source/rails_on_rack.md

@@ -5,7 +5,6 @@ This guide covers Rails integration with Rack and interfacing with other Rack co
 
 After reading this guide, you will know:
 
-* How to create Rails Metal applications.
 * How to use Rack Middlewares in your Rails applications.
 * Action Pack's internal Middleware stack.
 * How to define a custom Middleware stack.
@@ -19,7 +18,7 @@ Introduction to Rack
 
 Rack provides a minimal, modular and adaptable interface for developing web applications in Ruby. By wrapping HTTP requests and responses in the simplest way possible, it unifies and distills the API for web servers, web frameworks, and software in between (the so-called middleware) into a single method call.
 
-- [Rack API Documentation](http://rack.rubyforge.org/doc/)
+* [Rack API Documentation](http://rack.github.io/)
 
 Explaining Rack is not really in the scope of this guide. In case you are not familiar with Rack's basics, you should check out the [Resources](#resources) section below.
 
@@ -28,10 +27,9 @@ Rails on Rack
 
 ### Rails Application's Rack Object
 
-`ApplicationName::Application` is the primary Rack application object of a Rails
+`Rails.application` is the primary Rack application object of a Rails
 application. Any Rack compliant web server should be using
-`ApplicationName::Application` object to serve a Rails
-application. `Rails.application` refers to the same application object.
+`Rails.application` object to serve a Rails application.
 
 ### `rails server`
 
@@ -82,9 +80,8 @@ To use `rackup` instead of Rails' `rails server`, you can put the following insi
 
 ```ruby
 # Rails.root/config.ru
-require ::File.expand_path('../config/environment',  __FILE__)
+require ::File.expand_path('../config/environment', __FILE__)
 
-use Rack::Debugger
 use Rack::ContentLength
 run Rails.application
 ```
@@ -101,6 +98,10 @@ To find out more about different `rackup` options:
 $ rackup --help
 ```
 
+### Development and auto-reloading
+
+Middlewares are loaded once and are not monitored for changes. You will have to restart the server for changes to be reflected in the running application.
+
 Action Dispatcher Middleware Stack
 ----------------------------------
 
@@ -113,12 +114,13 @@ NOTE: `ActionDispatch::MiddlewareStack` is Rails equivalent of `Rack::Builder`,
 Rails has a handy rake task for inspecting the middleware stack in use:
 
 ```bash
-$ rake middleware
+$ bin/rake middleware
 ```
 
 For a freshly generated Rails application, this might produce something like:
 
 ```ruby
+use Rack::Sendfile
 use ActionDispatch::Static
 use Rack::Lock
 use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware:0x000000029a0838>
@@ -131,6 +133,7 @@ use ActionDispatch::DebugExceptions
 use ActionDispatch::RemoteIp
 use ActionDispatch::Reloader
 use ActionDispatch::Callbacks
+use ActiveRecord::Migration::CheckPending
 use ActiveRecord::ConnectionAdapters::ConnectionManagement
 use ActiveRecord::QueryCache
 use ActionDispatch::Cookies
@@ -140,10 +143,10 @@ use ActionDispatch::ParamsParser
 use Rack::Head
 use Rack::ConditionalGet
 use Rack::ETag
-run MyApp::Application.routes
+run Rails.application.routes
 ```
 
-Purpose of each of this middlewares is explained in the [Internal Middlewares](#internal-middleware-stack) section.
+The default middlewares shown here (and some others) are each summarized in the [Internal Middlewares](#internal-middleware-stack) section, below.
 
 ### Configuring Middleware Stack
 
@@ -181,27 +184,26 @@ You can swap an existing middleware in the middleware stack using `config.middle
 config.middleware.swap ActionDispatch::ShowExceptions, Lifo::ShowExceptions
 ```
 
-#### Middleware Stack is an Enumerable
-
-The middleware stack behaves just like a normal `Enumerable`. You can use any `Enumerable` methods to manipulate or interrogate the stack. The middleware stack also implements some `Array` methods including `[]`, `unshift` and `delete`. Methods described in the section above are just convenience methods.
+#### Deleting a Middleware
 
-Append following lines to your application configuration:
+Add the following lines to your application configuration:
 
 ```ruby
 # config/application.rb
 config.middleware.delete "Rack::Lock"
 ```
 
-And now if you inspect the middleware stack, you'll find that `Rack::Lock` will not be part of it.
+And now if you inspect the middleware stack, you'll find that `Rack::Lock` is
+not a part of it.
 
 ```bash
-$ rake middleware
+$ bin/rake middleware
 (in /Users/lifo/Rails/blog)
 use ActionDispatch::Static
 use #<ActiveSupport::Cache::Strategy::LocalCache::Middleware:0x00000001c304c8>
 use Rack::Runtime
 ...
-run Blog::Application.routes
+run Rails.application.routes
 ```
 
 If you want to remove session related middleware, do the following:
@@ -224,112 +226,100 @@ config.middleware.delete "Rack::MethodOverride"
 
 Much of Action Controller's functionality is implemented as Middlewares. The following list explains the purpose of each of them:
 
- **`ActionDispatch::Static`**
+**`Rack::Sendfile`**
+
+* Sets server specific X-Sendfile header. Configure this via `config.action_dispatch.x_sendfile_header` option.
+
+**`ActionDispatch::Static`**
 
-* Used to serve static assets. Disabled if `config.serve_static_assets` is true.
+* Used to serve static files. Disabled if `config.serve_static_files` is `false`.
 
- **`Rack::Lock`**
+**`Rack::Lock`**
 
 * Sets `env["rack.multithread"]` flag to `false` and wraps the application within a Mutex.
 
- **`ActiveSupport::Cache::Strategy::LocalCache::Middleware`**
+**`ActiveSupport::Cache::Strategy::LocalCache::Middleware`**
 
 * Used for memory caching. This cache is not thread safe.
 
- **`Rack::Runtime`**
+**`Rack::Runtime`**
 
 * Sets an X-Runtime header, containing the time (in seconds) taken to execute the request.
 
- **`Rack::MethodOverride`**
+**`Rack::MethodOverride`**
 
 * Allows the method to be overridden if `params[:_method]` is set. This is the middleware which supports the PUT and DELETE HTTP method types.
 
- **`ActionDispatch::RequestId`**
+**`ActionDispatch::RequestId`**
 
 * Makes a unique `X-Request-Id` header available to the response and enables the `ActionDispatch::Request#uuid` method.
 
- **`Rails::Rack::Logger`**
+**`Rails::Rack::Logger`**
 
 * Notifies the logs that the request has began. After request is complete, flushes all the logs.
 
- **`ActionDispatch::ShowExceptions`**
+**`ActionDispatch::ShowExceptions`**
 
 * Rescues any exception returned by the application and calls an exceptions app that will wrap it in a format for the end user.
 
- **`ActionDispatch::DebugExceptions`**
+**`ActionDispatch::DebugExceptions`**
 
 * Responsible for logging exceptions and showing a debugging page in case the request is local.
 
- **`ActionDispatch::RemoteIp`**
+**`ActionDispatch::RemoteIp`**
 
 * Checks for IP spoofing attacks.
 
- **`ActionDispatch::Reloader`**
+**`ActionDispatch::Reloader`**
 
 * Provides prepare and cleanup callbacks, intended to assist with code reloading during development.
 
- **`ActionDispatch::Callbacks`**
+**`ActionDispatch::Callbacks`**
 
-* Runs the prepare callbacks before serving the request.
+* Provides callbacks to be executed before and after dispatching the request.
 
- **`ActiveRecord::ConnectionAdapters::ConnectionManagement`**
+**`ActiveRecord::Migration::CheckPending`**
+
+* Checks pending migrations and raises `ActiveRecord::PendingMigrationError` if any migrations are pending.
+
+**`ActiveRecord::ConnectionAdapters::ConnectionManagement`**
 
 * Cleans active connections after each request, unless the `rack.test` key in the request environment is set to `true`.
 
- **`ActiveRecord::QueryCache`**
+**`ActiveRecord::QueryCache`**
 
 * Enables the Active Record query cache.
 
- **`ActionDispatch::Cookies`**
+**`ActionDispatch::Cookies`**
 
 * Sets cookies for the request.
 
- **`ActionDispatch::Session::CookieStore`**
+**`ActionDispatch::Session::CookieStore`**
 
 * Responsible for storing the session in cookies.
 
- **`ActionDispatch::Flash`**
+**`ActionDispatch::Flash`**
 
 * Sets up the flash keys. Only available if `config.action_controller.session_store` is set to a value.
 
- **`ActionDispatch::ParamsParser`**
+**`ActionDispatch::ParamsParser`**
 
 * Parses out parameters from the request into `params`.
 
- **`ActionDispatch::Head`**
+**`Rack::Head`**
 
 * Converts HEAD requests to `GET` requests and serves them as so.
 
- **`Rack::ConditionalGet`**
+**`Rack::ConditionalGet`**
 
 * Adds support for "Conditional `GET`" so that server responds with nothing if page wasn't changed.
 
- **`Rack::ETag`**
+**`Rack::ETag`**
 
 * Adds ETag header on all String bodies. ETags are used to validate cache.
 
 TIP: It's possible to use any of the above middlewares in your custom Rack stack.
 
-### Using Rack Builder
-
-The following shows how to replace use `Rack::Builder` instead of the Rails supplied `MiddlewareStack`.
-
-<strong>Clear the existing Rails middleware stack</strong>
-
-```ruby
-# config/application.rb
-config.middleware.clear
-```
-
-<br />
-<strong>Add a `config.ru` file to `Rails.root`</strong>
-
-```ruby
-# config.ru
-use MyOwnStackFromScratch
-run Rails.application
-```
-
 Resources
 ---------
 

data/guides/source/routing.md

@@ -36,7 +36,7 @@ the request is dispatched to the `patients` controller's `show` action with `{ i
 
 ### Generating Paths and URLs from Code
 
-You can also generate paths and URLs.  If the route above is modified to be:
+You can also generate paths and URLs. If the route above is modified to be:
 
 ```ruby
 get '/patients/:id', to: 'patients#show', as: 'patient'
@@ -89,15 +89,15 @@ resources :photos
 
 creates seven different routes in your application, all mapping to the `Photos` controller:
 
-| HTTP Verb | Path             | Action  | Used for                                     |
-| --------- | ---------------- | ------- | -------------------------------------------- |
-| GET       | /photos          | index   | display a list of all photos                 |
-| GET       | /photos/new      | new     | return an HTML form for creating a new photo |
-| POST      | /photos          | create  | create a new photo                           |
-| GET       | /photos/:id      | show    | display a specific photo                     |
-| GET       | /photos/:id/edit | edit    | return an HTML form for editing a photo      |
-| PATCH/PUT | /photos/:id      | update  | update a specific photo                      |
-| DELETE    | /photos/:id      | destroy | delete a specific photo                      |
+| HTTP Verb | Path             | Controller#Action | Used for                                     |
+| --------- | ---------------- | ----------------- | -------------------------------------------- |
+| GET       | /photos          | photos#index      | display a list of all photos                 |
+| GET       | /photos/new      | photos#new        | return an HTML form for creating a new photo |
+| POST      | /photos          | photos#create     | create a new photo                           |
+| GET       | /photos/:id      | photos#show       | display a specific photo                     |
+| GET       | /photos/:id/edit | photos#edit       | return an HTML form for editing a photo      |
+| PATCH/PUT | /photos/:id      | photos#update     | update a specific photo                      |
+| DELETE    | /photos/:id      | photos#destroy    | delete a specific photo                      |
 
 NOTE: Because the router uses the HTTP verb and URL to match inbound requests, four URLs map to seven different actions.
 
@@ -138,7 +138,7 @@ Sometimes, you have a resource that clients always look up without referencing a
 get 'profile', to: 'users#show'
 ```
 
-Passing a `String` to `match` will expect a `controller#action` format, while passing a `Symbol` will map directly to an action:
+Passing a `String` to `get` will expect a `controller#action` format, while passing a `Symbol` will map directly to an action:
 
 ```ruby
 get 'profile', to: :show
@@ -152,14 +152,14 @@ resource :geocoder
 
 creates six different routes in your application, all mapping to the `Geocoders` controller:
 
-| HTTP Verb | Path           | Action  | Used for                                      |
-| --------- | -------------- | ------- | --------------------------------------------- |
-| GET       | /geocoder/new  | new     | return an HTML form for creating the geocoder |
-| POST      | /geocoder      | create  | create the new geocoder                       |
-| GET       | /geocoder      | show    | display the one and only geocoder resource    |
-| GET       | /geocoder/edit | edit    | return an HTML form for editing the geocoder  |
-| PATCH/PUT | /geocoder      | update  | update the one and only geocoder resource     |
-| DELETE    | /geocoder      | destroy | delete the geocoder resource                  |
+| HTTP Verb | Path           | Controller#Action | Used for                                      |
+| --------- | -------------- | ----------------- | --------------------------------------------- |
+| GET       | /geocoder/new  | geocoders#new     | return an HTML form for creating the geocoder |
+| POST      | /geocoder      | geocoders#create  | create the new geocoder                       |
+| GET       | /geocoder      | geocoders#show    | display the one and only geocoder resource    |
+| GET       | /geocoder/edit | geocoders#edit    | return an HTML form for editing the geocoder  |
+| PATCH/PUT | /geocoder      | geocoders#update  | update the one and only geocoder resource     |
+| DELETE    | /geocoder      | geocoders#destroy | delete the geocoder resource                  |
 
 NOTE: Because you might want to use the same controller for a singular route (`/account`) and a plural route (`/accounts/45`), singular resources map to plural controllers. So that, for example, `resource :photo` and `resources :photos` creates both singular and plural routes that map to the same controller (`PhotosController`).
 
@@ -171,67 +171,75 @@ A singular resourceful route generates these helpers:
 
 As with plural resources, the same helpers ending in `_url` will also include the host, port and path prefix.
 
+WARNING: A [long-standing bug](https://github.com/rails/rails/issues/1769) prevents `form_for` from working automatically with singular resources. As a workaround, specify the URL for the form directly, like so:
+
+```ruby
+form_for @geocoder, url: geocoder_path do |f|
+```
+
 ### Controller Namespaces and Routing
 
 You may wish to organize groups of controllers under a namespace. Most commonly, you might group a number of administrative controllers under an `Admin::` namespace. You would place these controllers under the `app/controllers/admin` directory, and you can group them together in your router:
 
 ```ruby
 namespace :admin do
-  resources :posts, :comments
+  resources :articles, :comments
 end
 ```
 
-This will create a number of routes for each of the `posts` and `comments` controller. For `Admin::PostsController`, Rails will create:
+This will create a number of routes for each of the `articles` and `comments` controller. For `Admin::ArticlesController`, Rails will create:
 
-| HTTP Verb | Path                  | Action  | Used for                  |
-| --------- | --------------------- | ------- | ------------------------- |
-| GET       | /admin/posts          | index   | admin_posts_path          |
-| GET       | /admin/posts/new      | new     | new_admin_post_path       |
-| POST      | /admin/posts          | create  | admin_posts_path          |
-| GET       | /admin/posts/:id      | show    | admin_post_path(:id)      |
-| GET       | /admin/posts/:id/edit | edit    | edit_admin_post_path(:id) |
-| PATCH/PUT | /admin/posts/:id      | update  | admin_post_path(:id)      |
-| DELETE    | /admin/posts/:id      | destroy | admin_post_path(:id)      |
+| HTTP Verb | Path                     | Controller#Action      | Named Helper              |
+| --------- | ------------------------ | ---------------------- | ---------------------------- |
+| GET       | /admin/articles          | admin/articles#index   | admin_articles_path          |
+| GET       | /admin/articles/new      | admin/articles#new     | new_admin_article_path       |
+| POST      | /admin/articles          | admin/articles#create  | admin_articles_path          |
+| GET       | /admin/articles/:id      | admin/articles#show    | admin_article_path(:id)      |
+| GET       | /admin/articles/:id/edit | admin/articles#edit    | edit_admin_article_path(:id) |
+| PATCH/PUT | /admin/articles/:id      | admin/articles#update  | admin_article_path(:id)      |
+| DELETE    | /admin/articles/:id      | admin/articles#destroy | admin_article_path(:id)      |
 
-If you want to route `/posts` (without the prefix `/admin`) to `Admin::PostsController`, you could use:
+If you want to route `/articles` (without the prefix `/admin`) to `Admin::ArticlesController`, you could use:
 
 ```ruby
 scope module: 'admin' do
-  resources :posts, :comments
+  resources :articles, :comments
 end
 ```
 
 or, for a single case:
 
 ```ruby
-resources :posts, module: 'admin'
+resources :articles, module: 'admin'
 ```
 
-If you want to route `/admin/posts` to `PostsController` (without the `Admin::` module prefix), you could use:
+If you want to route `/admin/articles` to `ArticlesController` (without the `Admin::` module prefix), you could use:
 
 ```ruby
 scope '/admin' do
-  resources :posts, :comments
+  resources :articles, :comments
 end
 ```
 
 or, for a single case:
 
 ```ruby
-resources :posts, path: '/admin/posts'
+resources :articles, path: '/admin/articles'
 ```
 
-In each of these cases, the named routes remain the same as if you did not use `scope`. In the last case, the following paths map to `PostsController`:
+In each of these cases, the named routes remain the same as if you did not use `scope`. In the last case, the following paths map to `ArticlesController`:
 
-| HTTP Verb | Path                  | Action  | Named Helper        |
-| --------- | --------------------- | ------- | ------------------- |
-| GET       | /admin/posts          | index   | posts_path          |
-| GET       | /admin/posts/new      | new     | new_post_path       |
-| POST      | /admin/posts          | create  | posts_path          |
-| GET       | /admin/posts/:id      | show    | post_path(:id)      |
-| GET       | /admin/posts/:id/edit | edit    | edit_post_path(:id) |
-| PATCH/PUT | /admin/posts/:id      | update  | post_path(:id)      |
-| DELETE    | /admin/posts/:id      | destroy | post_path(:id)      |
+| HTTP Verb | Path                     | Controller#Action    | Named Helper           |
+| --------- | ------------------------ | -------------------- | ---------------------- |
+| GET       | /admin/articles          | articles#index       | articles_path          |
+| GET       | /admin/articles/new      | articles#new         | new_article_path       |
+| POST      | /admin/articles          | articles#create      | articles_path          |
+| GET       | /admin/articles/:id      | articles#show        | article_path(:id)      |
+| GET       | /admin/articles/:id/edit | articles#edit        | edit_article_path(:id) |
+| PATCH/PUT | /admin/articles/:id      | articles#update      | article_path(:id)      |
+| DELETE    | /admin/articles/:id      | articles#destroy     | article_path(:id)      |
+
+TIP: _If you need to use a different controller namespace inside a `namespace` block you can specify an absolute controller path, e.g: `get '/foo' => '/foo#index'`._
 
 ### Nested Resources
 
@@ -257,15 +265,15 @@ end
 
 In addition to the routes for magazines, this declaration will also route ads to an `AdsController`. The ad URLs require a magazine:
 
-| HTTP Verb | Path                                 | Action  | Used for                                                                   |
-| --------- | ------------------------------------ | ------- | -------------------------------------------------------------------------- |
-| GET       | /magazines/:magazine_id/ads          | index   | display a list of all ads for a specific magazine                          |
-| GET       | /magazines/:magazine_id/ads/new      | new     | return an HTML form for creating a new ad belonging to a specific magazine |
-| POST      | /magazines/:magazine_id/ads          | create  | create a new ad belonging to a specific magazine                           |
-| GET       | /magazines/:magazine_id/ads/:id      | show    | display a specific ad belonging to a specific magazine                     |
-| GET       | /magazines/:magazine_id/ads/:id/edit | edit    | return an HTML form for editing an ad belonging to a specific magazine     |
-| PATCH/PUT | /magazines/:magazine_id/ads/:id      | update  | update a specific ad belonging to a specific magazine                      |
-| DELETE    | /magazines/:magazine_id/ads/:id      | destroy | delete a specific ad belonging to a specific magazine                      |
+| HTTP Verb | Path                                 | Controller#Action | Used for                                                                   |
+| --------- | ------------------------------------ | ----------------- | -------------------------------------------------------------------------- |
+| GET       | /magazines/:magazine_id/ads          | ads#index         | display a list of all ads for a specific magazine                          |
+| GET       | /magazines/:magazine_id/ads/new      | ads#new           | return an HTML form for creating a new ad belonging to a specific magazine |
+| POST      | /magazines/:magazine_id/ads          | ads#create        | create a new ad belonging to a specific magazine                           |
+| GET       | /magazines/:magazine_id/ads/:id      | ads#show          | display a specific ad belonging to a specific magazine                     |
+| GET       | /magazines/:magazine_id/ads/:id/edit | ads#edit          | return an HTML form for editing an ad belonging to a specific magazine     |
+| PATCH/PUT | /magazines/:magazine_id/ads/:id      | ads#update        | update a specific ad belonging to a specific magazine                      |
+| DELETE    | /magazines/:magazine_id/ads/:id      | ads#destroy       | delete a specific ad belonging to a specific magazine                      |
 
 This will also create routing helpers such as `magazine_ads_url` and `edit_magazine_ad_path`. These helpers take an instance of Magazine as the first parameter (`magazine_ads_url(@magazine)`).
 
@@ -296,7 +304,7 @@ TIP: _Resources should never be nested more than 1 level deep._
 One way to avoid deep nesting (as recommended above) is to generate the collection actions scoped under the parent, so as to get a sense of the hierarchy, but to not nest the member actions. In other words, to only build routes with the minimal amount of information to uniquely identify the resource, like this:
 
 ```ruby
-resources :posts do
+resources :articles do
   resources :comments, only: [:index, :new, :create]
 end
 resources :comments, only: [:show, :edit, :update, :destroy]
@@ -305,7 +313,7 @@ resources :comments, only: [:show, :edit, :update, :destroy]
 This idea strikes a balance between descriptive routes and deep nesting. There exists shorthand syntax to achieve just that, via the `:shallow` option:
 
 ```ruby
-resources :posts do
+resources :articles do
   resources :comments, shallow: true
 end
 ```
@@ -313,7 +321,7 @@ end
 This will generate the exact same routes as the first example. You can also specify the `:shallow` option in the parent resource, in which case all of the nested resources will be shallow:
 
 ```ruby
-resources :posts, shallow: true do
+resources :articles, shallow: true do
   resources :comments
   resources :quotes
   resources :drafts
@@ -324,7 +332,7 @@ The `shallow` method of the DSL creates a scope inside of which every nesting is
 
 ```ruby
 shallow do
-  resources :posts do
+  resources :articles do
     resources :comments
     resources :quotes
     resources :drafts
@@ -332,11 +340,11 @@ shallow do
 end
 ```
 
-There exists two options for `scope` to customize shallow routes. `:shallow_path` prefixes member paths with the specified parameter:
+There exist two options for `scope` to customize shallow routes. `:shallow_path` prefixes member paths with the specified parameter:
 
 ```ruby
 scope shallow_path: "sekret" do
-  resources :posts do
+  resources :articles do
     resources :comments, shallow: true
   end
 end
@@ -344,21 +352,21 @@ end
 
 The comments resource here will have the following routes generated for it:
 
-| HTTP Verb | Path                                   | Named Helper        |
-| --------- | -------------------------------------- | ------------------- |
-| GET       | /posts/:post_id/comments(.:format)     | post_comments       |
-| POST      | /posts/:post_id/comments(.:format)     | post_comments       |
-| GET       | /posts/:post_id/comments/new(.:format) | new_post_comment    |
-| GET       | /sekret/comments/:id/edit(.:format)    | edit_comment        |
-| GET       | /sekret/comments/:id(.:format)         | comment             |
-| PATCH/PUT | /sekret/comments/:id(.:format)         | comment             |
-| DELETE    | /sekret/comments/:id(.:format)         | comment             |
+| HTTP Verb | Path                                         | Controller#Action | Named Helper             |
+| --------- | -------------------------------------------- | ----------------- | ------------------------ |
+| GET       | /articles/:article_id/comments(.:format)     | comments#index    | article_comments_path    |
+| POST      | /articles/:article_id/comments(.:format)     | comments#create   | article_comments_path    |
+| GET       | /articles/:article_id/comments/new(.:format) | comments#new      | new_article_comment_path |
+| GET       | /sekret/comments/:id/edit(.:format)          | comments#edit     | edit_comment_path        |
+| GET       | /sekret/comments/:id(.:format)               | comments#show     | comment_path             |
+| PATCH/PUT | /sekret/comments/:id(.:format)               | comments#update   | comment_path             |
+| DELETE    | /sekret/comments/:id(.:format)               | comments#destroy  | comment_path             |
 
 The `:shallow_prefix` option adds the specified parameter to the named helpers:
 
 ```ruby
 scope shallow_prefix: "sekret" do
-  resources :posts do
+  resources :articles do
     resources :comments, shallow: true
   end
 end
@@ -366,19 +374,19 @@ end
 
 The comments resource here will have the following routes generated for it:
 
-| HTTP Verb | Path                                   | Named Helper        |
-| --------- | -------------------------------------- | ------------------- |
-| GET       | /posts/:post_id/comments(.:format)     | post_comments       |
-| POST      | /posts/:post_id/comments(.:format)     | post_comments       |
-| GET       | /posts/:post_id/comments/new(.:format) | new_post_comment    |
-| GET       | /comments/:id/edit(.:format)           | edit_sekret_comment |
-| GET       | /comments/:id(.:format)                | sekret_comment      |
-| PATCH/PUT | /comments/:id(.:format)                | sekret_comment      |
-| DELETE    | /comments/:id(.:format)                | sekret_comment      |
+| HTTP Verb | Path                                         | Controller#Action | Named Helper                |
+| --------- | -------------------------------------------- | ----------------- | --------------------------- |
+| GET       | /articles/:article_id/comments(.:format)     | comments#index    | article_comments_path       |
+| POST      | /articles/:article_id/comments(.:format)     | comments#create   | article_comments_path       |
+| GET       | /articles/:article_id/comments/new(.:format) | comments#new      | new_article_comment_path    |
+| GET       | /comments/:id/edit(.:format)                 | comments#edit     | edit_sekret_comment_path    |
+| GET       | /comments/:id(.:format)                      | comments#show     | sekret_comment_path         |
+| PATCH/PUT | /comments/:id(.:format)                      | comments#update   | sekret_comment_path         |
+| DELETE    | /comments/:id(.:format)                      | comments#destroy  | sekret_comment_path         |
 
 ### Routing concerns
 
-Routing Concerns allows you to declare common routes that can be reused inside others resources and routes. To define a concern:
+Routing Concerns allows you to declare common routes that can be reused inside other resources and routes. To define a concern:
 
 ```ruby
 concern :commentable do
@@ -395,7 +403,7 @@ These concerns can be used in resources to avoid code duplication and share beha
 ```ruby
 resources :messages, concerns: :commentable
 
-resources :posts, concerns: [:commentable, :image_attachable]
+resources :articles, concerns: [:commentable, :image_attachable]
 ```
 
 The above is equivalent to:
@@ -405,7 +413,7 @@ resources :messages do
   resources :comments
 end
 
-resources :posts do
+resources :articles do
   resources :comments
   resources :images, only: :index
 end
@@ -414,7 +422,7 @@ end
 Also you can use them in any place that you want inside the routes, for example in a scope or namespace call:
 
 ```ruby
-namespace :posts do
+namespace :articles do
   concerns :commentable
 end
 ```
@@ -479,7 +487,10 @@ end
 
 This will recognize `/photos/1/preview` with GET, and route to the `preview` action of `PhotosController`, with the resource id value passed in `params[:id]`. It will also create the `preview_photo_url` and `preview_photo_path` helpers.
 
-Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use `get`, `patch`, `put`, `post`, or `delete` here. If you don't have multiple `member` routes, you can also pass `:on` to a route, eliminating the block:
+Within the block of member routes, each route name specifies the HTTP verb
+will be recognized. You can use `get`, `patch`, `put`, `post`, or `delete` here
+. If you don't have multiple `member` routes, you can also pass `:on` to a
+route, eliminating the block:
 
 ```ruby
 resources :photos do
@@ -600,6 +611,8 @@ get 'photos/:id', to: 'photos#show', defaults: { format: 'jpg' }
 
 Rails would match `photos/12` to the `show` action of `PhotosController`, and set `params[:format]` to `"jpg"`.
 
+NOTE: You cannot override defaults via query parameters - this is for security reasons. The only defaults that can be overridden are dynamic segments via substitution in the URL path.
+
 ### Naming Routes
 
 You can specify a name for any route using the `:as` option:
@@ -620,7 +633,7 @@ This will define a `user_path` method that will be available in controllers, hel
 
 ### HTTP Verb Constraints
 
-In general, you should use the `get`, `post`, `put` and `delete` methods to constrain a route to a particular verb. You can use the `match` method with the `:via` option to match multiple verbs at once:
+In general, you should use the `get`, `post`, `put`, `patch`  and `delete` methods to constrain a route to a particular verb. You can use the `match` method with the `:via` option to match multiple verbs at once:
 
 ```ruby
 match 'photos', to: 'photos#show', via: [:get, :post]
@@ -634,6 +647,8 @@ match 'photos', to: 'photos#show', via: :all
 
 NOTE: Routing both `GET` and `POST` requests to a single action has security implications. In general, you should avoid routing all verbs to an action unless you have a good reason to.
 
+NOTE: 'GET' in Rails won't check for CSRF token. You should never write to the database from 'GET' requests, for more information see the [security guide](security.html#csrf-countermeasures) on CSRF countermeasures.
+
 ### Segment Constraints
 
 You can use the `:constraints` option to enforce a format for a dynamic segment:
@@ -651,26 +666,26 @@ get 'photos/:id', to: 'photos#show', id: /[A-Z]\d{5}/
 `:constraints` takes regular expressions with the restriction that regexp anchors can't be used. For example, the following route will not work:
 
 ```ruby
-get '/:id', to: 'posts#show', constraints: {id: /^\d/}
+get '/:id', to: 'articles#show', constraints: { id: /^\d/ }
 ```
 
 However, note that you don't need to use anchors because all routes are anchored at the start.
 
-For example, the following routes would allow for `posts` with `to_param` values like `1-hello-world` that always begin with a number and `users` with `to_param` values like `david` that never begin with a number to share the root namespace:
+For example, the following routes would allow for `articles` with `to_param` values like `1-hello-world` that always begin with a number and `users` with `to_param` values like `david` that never begin with a number to share the root namespace:
 
 ```ruby
-get '/:id', to: 'posts#show', constraints: { id: /\d.+/ }
+get '/:id', to: 'articles#show', constraints: { id: /\d.+/ }
 get '/:username', to: 'users#show'
 ```
 
 ### Request-Based Constraints
 
-You can also constrain a route based on any method on the <a href="action_controller_overview.html#the-request-object">Request</a> object that returns a `String`.
+You can also constrain a route based on any method on the [Request object](action_controller_overview.html#the-request-object) that returns a `String`.
 
 You specify a request-based constraint the same way that you specify a segment constraint:
 
 ```ruby
-get 'photos', constraints: {subdomain: 'admin'}
+get 'photos', to: 'photos#index', constraints: { subdomain: 'admin' }
 ```
 
 You can also specify constraints in a block form:
@@ -683,6 +698,8 @@ namespace :admin do
 end
 ```
 
+NOTE: Request constraints work by calling a method on the [Request object](action_controller_overview.html#the-request-object) with the same name as the hash key and then compare the return value with the hash value. Therefore, constraint values should match the corresponding Request object method return type. For example: `constraints: { subdomain: 'api' }` will match an `api` subdomain as expected, however using a symbol `constraints: { subdomain: :api }` will not, because `request.subdomain` returns `'api'` as a String.
+
 ### Advanced Constraints
 
 If you have a more advanced constraint, you can provide an object that responds to `matches?` that Rails should use. Let's say you wanted to route all users on a blacklist to the `BlacklistController`. You could do:
@@ -698,7 +715,7 @@ class BlacklistConstraint
   end
 end
 
-TwitterClone::Application.routes.draw do
+Rails.application.routes.draw do
   get '*path', to: 'blacklist#index',
     constraints: BlacklistConstraint.new
 end
@@ -707,7 +724,7 @@ end
 You can also specify constraints as a lambda:
 
 ```ruby
-TwitterClone::Application.routes.draw do
+Rails.application.routes.draw do
   get '*path', to: 'blacklist#index',
     constraints: lambda { |request| Blacklist.retrieve_ips.include?(request.remote_ip) }
 end
@@ -741,7 +758,7 @@ get '*a/foo/*b', to: 'test#index'
 
 would match `zoo/woo/foo/bar/baz` with `params[:a]` equals `'zoo/woo'`, and `params[:b]` equals `'bar/baz'`.
 
-NOTE: By requesting `'/foo/bar.json'`, your `params[:pages]` will be equals to `'foo/bar'` with the request format of JSON. If you want the old 3.0.x behavior back, you could supply `format: false` like this:
+NOTE: By requesting `'/foo/bar.json'`, your `params[:pages]` will be equal to `'foo/bar'` with the request format of JSON. If you want the old 3.0.x behavior back, you could supply `format: false` like this:
 
 ```ruby
 get '*pages', to: 'pages#show', format: false
@@ -758,20 +775,20 @@ get '*pages', to: 'pages#show', format: true
 You can redirect any path to another path using the `redirect` helper in your router:
 
 ```ruby
-get '/stories', to: redirect('/posts')
+get '/stories', to: redirect('/articles')
 ```
 
 You can also reuse dynamic segments from the match in the path to redirect to:
 
 ```ruby
-get '/stories/:name', to: redirect('/posts/%{name}')
+get '/stories/:name', to: redirect('/articles/%{name}')
 ```
 
-You can also provide a block to redirect, which receives the params and the request object:
+You can also provide a block to redirect, which receives the symbolized path parameters and the request object:
 
 ```ruby
-get '/stories/:name', to: redirect {|params, req| "/posts/#{params[:name].pluralize}" }
-get '/stories', to: redirect {|p, req| "/posts/#{req.subdomain}" }
+get '/stories/:name', to: redirect { |path_params, req| "/articles/#{path_params[:name].pluralize}" }
+get '/stories', to: redirect { |path_params, req| "/articles/#{req.subdomain}" }
 ```
 
 Please note that this redirection is a 301 "Moved Permanently" redirect. Keep in mind that some web browsers or proxy servers will cache this type of redirect, making the old page inaccessible.
@@ -780,7 +797,7 @@ In all of these cases, if you don't provide the leading host (`http://www.exampl
 
 ### Routing to Rack Applications
 
-Instead of a String like `'posts#index'`, which corresponds to the `index` action in the `PostsController`, you can specify any <a href="rails_on_rack.html">Rack application</a> as the endpoint for a matcher:
+Instead of a String like `'articles#index'`, which corresponds to the `index` action in the `ArticlesController`, you can specify any [Rack application](rails_on_rack.html) as the endpoint for a matcher:
 
 ```ruby
 match '/application.js', to: Sprockets, via: :all
@@ -788,7 +805,19 @@ match '/application.js', to: Sprockets, via: :all
 
 As long as `Sprockets` responds to `call` and returns a `[status, headers, body]`, the router won't know the difference between the Rack application and an action. This is an appropriate use of `via: :all`, as you will want to allow your Rack application to handle all verbs as it considers appropriate.
 
-NOTE: For the curious, `'posts#index'` actually expands out to `PostsController.action(:index)`, which returns a valid Rack application.
+NOTE: For the curious, `'articles#index'` actually expands out to `ArticlesController.action(:index)`, which returns a valid Rack application.
+
+If you specify a rack application as the endpoint for a matcher remember that the route will be unchanged in the receiving application. With the following route your rack application should expect the route to be '/admin':
+
+```ruby
+match '/admin', to: AdminApp, via: :all
+```
+
+If you would prefer to have your rack application receive requests at the root path instead use mount:
+
+```ruby
+mount AdminApp, at: '/admin'
+```
 
 ### Using `root`
 
@@ -803,7 +832,7 @@ You should put the `root` route at the top of the file, because it is the most p
 
 NOTE: The `root` route only routes `GET` requests to the action.
 
-You can also use root inside namespaces and scopes as well.  For example:
+You can also use root inside namespaces and scopes as well. For example:
 
 ```ruby
 namespace :admin do
@@ -824,7 +853,7 @@ get 'こんにちは', to: 'welcome#index'
 Customizing Resourceful Routes
 ------------------------------
 
-While the default routes and helpers generated by `resources :posts` will usually serve you well, you may want to customize them in some way. Rails allows you to customize virtually any generic part of the resourceful helpers.
+While the default routes and helpers generated by `resources :articles` will usually serve you well, you may want to customize them in some way. Rails allows you to customize virtually any generic part of the resourceful helpers.
 
 ### Specifying a Controller to Use
 
@@ -836,15 +865,15 @@ resources :photos, controller: 'images'
 
 will recognize incoming paths beginning with `/photos` but route to the `Images` controller:
 
-| HTTP Verb | Path             | Action  | Named Helper         |
-| --------- | ---------------- | ------- | -------------------- |
-| GET       | /photos          | index   | photos_path          |
-| GET       | /photos/new      | new     | new_photo_path       |
-| POST      | /photos          | create  | photos_path          |
-| GET       | /photos/:id      | show    | photo_path(:id)      |
-| GET       | /photos/:id/edit | edit    | edit_photo_path(:id) |
-| PATCH/PUT | /photos/:id      | update  | photo_path(:id)      |
-| DELETE    | /photos/:id      | destroy | photo_path(:id)      |
+| HTTP Verb | Path             | Controller#Action | Named Helper         |
+| --------- | ---------------- | ----------------- | -------------------- |
+| GET       | /photos          | images#index      | photos_path          |
+| GET       | /photos/new      | images#new        | new_photo_path       |
+| POST      | /photos          | images#create     | photos_path          |
+| GET       | /photos/:id      | images#show       | photo_path(:id)      |
+| GET       | /photos/:id/edit | images#edit       | edit_photo_path(:id) |
+| PATCH/PUT | /photos/:id      | images#update     | photo_path(:id)      |
+| DELETE    | /photos/:id      | images#destroy    | photo_path(:id)      |
 
 NOTE: Use `photos_path`, `new_photo_path`, etc. to generate paths for this resource.
 
@@ -857,8 +886,8 @@ resources :user_permissions, controller: 'admin/user_permissions'
 This will route to the `Admin::UserPermissions` controller.
 
 NOTE: Only the directory notation is supported. Specifying the
-controller with ruby constant notation (eg. `:controller =>
-'Admin::UserPermissions'`) can lead to routing problems and results in
+controller with Ruby constant notation (eg. `controller: 'Admin::UserPermissions'`)
+can lead to routing problems and results in
 a warning.
 
 ### Specifying Constraints
@@ -866,7 +895,7 @@ a warning.
 You can use the `:constraints` option to specify a required format on the implicit `id`. For example:
 
 ```ruby
-resources :photos, constraints: {id: /[A-Z][A-Z][0-9]+/}
+resources :photos, constraints: { id: /[A-Z][A-Z][0-9]+/ }
 ```
 
 This declaration constrains the `:id` parameter to match the supplied regular expression. So, in this case, the router would no longer match `/photos/1` to this route. Instead, `/photos/RR27` would match.
@@ -894,19 +923,19 @@ resources :photos, as: 'images'
 
 will recognize incoming paths beginning with `/photos` and route the requests to `PhotosController`, but use the value of the :as option to name the helpers.
 
-| HTTP Verb | Path             | Action  | Named Helper         |
-| --------- | ---------------- | ------- | -------------------- |
-| GET       | /photos          | index   | images_path          |
-| GET       | /photos/new      | new     | new_image_path       |
-| POST      | /photos          | create  | images_path          |
-| GET       | /photos/:id      | show    | image_path(:id)      |
-| GET       | /photos/:id/edit | edit    | edit_image_path(:id) |
-| PATCH/PUT | /photos/:id      | update  | image_path(:id)      |
-| DELETE    | /photos/:id      | destroy | image_path(:id)      |
+| HTTP Verb | Path             | Controller#Action | Named Helper         |
+| --------- | ---------------- | ----------------- | -------------------- |
+| GET       | /photos          | photos#index      | images_path          |
+| GET       | /photos/new      | photos#new        | new_image_path       |
+| POST      | /photos          | photos#create     | images_path          |
+| GET       | /photos/:id      | photos#show       | image_path(:id)      |
+| GET       | /photos/:id/edit | photos#edit       | edit_image_path(:id) |
+| PATCH/PUT | /photos/:id      | photos#update     | image_path(:id)      |
+| DELETE    | /photos/:id      | photos#destroy    | image_path(:id)      |
 
 ### Overriding the `new` and `edit` Segments
 
-The `:path_names` option lets you override the automatically-generated "new" and "edit" segments in paths:
+The `:path_names` option lets you override the automatically-generated `new` and `edit` segments in paths:
 
 ```ruby
 resources :photos, path_names: { new: 'make', edit: 'change' }
@@ -941,7 +970,7 @@ end
 resources :photos
 ```
 
-This will provide route helpers such as `admin_photos_path`, `new_admin_photo_path` etc.
+This will provide route helpers such as `admin_photos_path`, `new_admin_photo_path`, etc.
 
 To prefix a group of route helpers, use `:as` with `scope`:
 
@@ -961,15 +990,15 @@ You can prefix routes with a named parameter also:
 
 ```ruby
 scope ':username' do
-  resources :posts
+  resources :articles
 end
 ```
 
-This will provide you with URLs such as `/bob/posts/1` and will allow you to reference the `username` part of the path as `params[:username]` in controllers, helpers and views.
+This will provide you with URLs such as `/bob/articles/1` and will allow you to reference the `username` part of the path as `params[:username]` in controllers, helpers and views.
 
 ### Restricting the Routes Created
 
-By default, Rails creates routes for the seven default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the `:only` and `:except` options to fine-tune this behavior. The `:only` option tells Rails to create only the specified routes:
+By default, Rails creates routes for the seven default actions (`index`, `show`, `new`, `create`, `edit`, `update`, and `destroy`) for every RESTful route in your application. You can use the `:only` and `:except` options to fine-tune this behavior. The `:only` option tells Rails to create only the specified routes:
 
 ```ruby
 resources :photos, only: [:index, :show]
@@ -999,15 +1028,15 @@ end
 
 Rails now creates routes to the `CategoriesController`.
 
-| HTTP Verb | Path                       | Action  | Used for                |
-| --------- | -------------------------- | ------- | ----------------------- |
-| GET       | /kategorien                | index   | categories_path         |
-| GET       | /kategorien/neu            | new     | new_category_path       |
-| POST      | /kategorien                | create  | categories_path         |
-| GET       | /kategorien/:id            | show    | category_path(:id)      |
-| GET       | /kategorien/:id/bearbeiten | edit    | edit_category_path(:id) |
-| PATCH/PUT | /kategorien/:id            | update  | category_path(:id)      |
-| DELETE    | /kategorien/:id            | destroy | category_path(:id)      |
+| HTTP Verb | Path                       | Controller#Action  | Named Helper            |
+| --------- | -------------------------- | ------------------ | ----------------------- |
+| GET       | /kategorien                | categories#index   | categories_path         |
+| GET       | /kategorien/neu            | categories#new     | new_category_path       |
+| POST      | /kategorien                | categories#create  | categories_path         |
+| GET       | /kategorien/:id            | categories#show    | category_path(:id)      |
+| GET       | /kategorien/:id/bearbeiten | categories#edit    | edit_category_path(:id) |
+| PATCH/PUT | /kategorien/:id            | categories#update  | category_path(:id)      |
+| DELETE    | /kategorien/:id            | categories#destroy | category_path(:id)      |
 
 ### Overriding the Singular Form
 
@@ -1031,6 +1060,28 @@ end
 
 This will create routing helpers such as `magazine_periodical_ads_url` and `edit_magazine_periodical_ad_path`.
 
+### Overriding Named Route Parameters
+
+The `:param` option overrides the default resource identifier `:id` (name of
+the [dynamic segment](routing.html#dynamic-segments) used to generate the
+routes). You can access that segment from your controller using
+`params[<:param>]`.
+
+```ruby
+resources :videos, param: :identifier
+```
+
+```
+     videos GET  /videos(.:format)                  videos#index
+            POST /videos(.:format)                  videos#create
+ new_videos GET  /videos/new(.:format)              videos#new
+edit_videos GET  /videos/:identifier/edit(.:format) videos#edit
+```
+
+```ruby
+Video.find_by(identifier: params[:identifier])
+```
+
 Inspecting and Testing Routes
 -----------------------------
 
@@ -1059,7 +1110,7 @@ edit_user GET    /users/:id/edit(.:format) users#edit
 You may restrict the listing to the routes that map to a particular controller setting the `CONTROLLER` environment variable:
 
 ```bash
-$ CONTROLLER=users rake routes
+$ CONTROLLER=users bin/rake routes
 ```
 
 TIP: You'll find that the output from `rake routes` is much more readable if you widen your terminal window until the output lines don't wrap.