rails 4.0.0 → 4.0.1.rc1

data/guides/source/getting_started.md

@@ -155,7 +155,7 @@ To begin with, let's get some text up on screen quickly. To do this, you need to
 
 ### Starting up the Web Server
 
-You actually have a functional Rails application already. To see it, you need to start a web server on your development machine. You can do this by running:
+You actually have a functional Rails application already. To see it, you need to start a web server on your development machine. You can do this by running the following in the root directory of your rails application:
 
 ```bash
 $ rails server
@@ -233,13 +233,13 @@ Blog::Application.routes.draw do
   # root to: "welcome#index"
 ```
 
-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:
+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` and uncomment it. It should look something like the following:
 
 ```ruby
-root to: "welcome#index"
+root "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> to the welcome controller's index action. This was created earlier when you ran the controller generator (`rails generate controller welcome index`).
+The `root "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> 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> 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.
 
@@ -264,7 +264,7 @@ Blog::Application.routes.draw do
 end
 ```
 
-If you run `rake routes`, you'll see that all the routes for the 
+If you run `rake routes`, you'll see that all the routes for the
 standard RESTful actions.
 
 ```bash
@@ -307,6 +307,10 @@ end
 
 A controller is simply a class that is defined to inherit from `ApplicationController`. It's inside this class that you'll define methods that will become the actions for this controller. These actions will perform CRUD operations on the posts within our system.
 
+NOTE: There are `public`, `private` and `protected` methods in `Ruby`
+(for more details you can check on [Programming Ruby](http://www.ruby-doc.org/docs/ProgrammingRuby/)).
+But only `public` methods can be actions for controllers.
+
 If you refresh <http://localhost:3000/posts/new> now, you'll get a new error:
 
 ![Unknown action new for PostsController!](images/getting_started/unknown_action_new_for_posts.png)
@@ -531,43 +535,70 @@ and change the `create` action to look like this:
 
 ```ruby
 def create
-  @post = Post.new(post_params)
- 
+  @post = Post.new(params[:post])
   @post.save
   redirect_to @post
 end
-
-private
-  def post_params
-    params.require(:post).permit(:title, :text)
-  end
 ```
 
 Here's what's going on: every Rails model can be initialized with its
 respective attributes, which are automatically mapped to the respective
 database columns. In the first line we do just that (remember that
-`post_params` contains the attributes we're interested in). Then,
+`params[:post]` contains the attributes we're interested in). Then,
 `@post.save` is responsible for saving the model in the database.
 Finally, we redirect the user to the `show` action,
 which we'll define later.
 
-TIP: Note that `def post_params` is private. This new approach prevents an attacker from setting the model's attributes by manipulating the hash passed to the model. For more information, refer to [this blog post about Strong Parameters](http://weblog.rubyonrails.org/2012/3/21/strong-parameters/).
-
 TIP: As we'll see later, `@post.save` returns a boolean indicating
 whether the model was saved or not.
 
+If you now go to
+<http://localhost:3000/posts/new> you'll *almost* be able to create a post. Try
+it! You should get an error that looks like this:
+
+![Forbidden attributes for new post](images/getting_started/forbidden_attributes_for_new_post.png)
+
+Rails has several security features that help you write secure applications,
+and you're running into one of them now. This one is called
+`strong_parameters`, which requires us to tell Rails exactly which parameters
+we want to accept in our controllers. In this case, we want to allow the
+`title` and `text` parameters, so change your `create` controller action to
+look like this:
+
+```ruby
+def create
+  @post = Post.new(post_params)
+
+  @post.save
+  redirect_to @post
+end
+
+private
+  def post_params
+    params.require(:post).permit(:title, :text)
+  end
+```
+
+See the `permit`? It allows us to accept both `title` and `text` in this
+action.
+
+TIP: Note that `def post_params` is private. This new approach prevents an attacker from
+setting the model's attributes by manipulating the hash passed to the model.
+For more information, refer to
+[this blog post about Strong Parameters](http://weblog.rubyonrails.org/2012/3/21/strong-parameters/).
+
 ### Showing Posts
 
 If you submit the form again now, Rails will complain about not finding
 the `show` action. That's not very useful though, so let's add the
-`show` action before proceeding. 
+`show` action before proceeding.
 
 ```ruby
 post GET    /posts/:id(.:format)      posts#show
 ```
 
 The special syntax `:id` tells rails that this route expects an `:id`
-parameter, which in our case will be the id of the post. 
+parameter, which in our case will be the id of the post.
 
 As we did before, we need to add the `show` action in
 `app/controllers/posts_controller.rb` and its respective view.
@@ -598,37 +629,14 @@ content:
 </p>
 ```
 
-If you now go to
-<http://localhost:3000/posts/new> you'll *almost* be able to create a post. Try
-it! You should get an error that looks like this:
-
-![Forbidden attributes for new post](images/getting_started/forbidden_attributes_for_new_post.png)
-
-Rails has several security features that help you write secure applications,
-and you're running into one of them now. This one is called
-'strong_parameters,' which requires us to tell Rails exactly which parameters
-we want to accept in our controllers. In this case, we want to allow the
-'title' and 'text' parameters, so change your `create` controller action to
-look like this:
-
-```
-  def create
-    @post = Post.new(params[:post].permit(:title, :text))
-
-    @post.save
-    redirect_to @post
-  end
-```
-
-See the `permit`? It allows us to accept both `title` and `text` in this
-action. With this change, you should finally be able to create new `Post`s.
+With this change, you should finally be able to create new posts.
 Visit <http://localhost:3000/posts/new> and give it a try!
 
 ![Show action for posts](images/getting_started/show_action_for_posts.png)
 
 ### Listing all posts
 
-We still need a way to list all our posts, so let's do that. 
+We still need a way to list all our posts, so let's do that.
 We'll use a specific route from `config/routes.rb`:
 
 ```ruby
@@ -770,7 +778,7 @@ def create
   @post = Post.new(params[:post].permit(:title, :text))
 
   if @post.save
-    redirect_to @post 
+    redirect_to @post
   else
     render 'new'
   end
@@ -793,7 +801,7 @@ something went wrong. To do that, you'll modify
 ```html+erb
 <%= form_for :post, url: posts_path do |f| %>
   <% if @post.errors.any? %>
-  <div id="errorExplanation">
+  <div id="error_explanation">
     <h2><%= pluralize(@post.errors.count, "error") %> prohibited
       this post from being saved:</h2>
     <ul>
@@ -860,10 +868,9 @@ it look as follows:
 ```html+erb
 <h1>Editing post</h1>
 
-<%= form_for :post, url: post_path(@post.id) },
-method: :patch do |f| %>
+<%= form_for :post, url: post_path(@post), method: :patch do |f| %>
   <% if @post.errors.any? %>
-  <div id="errorExplanation">
+  <div id="error_explanation">
     <h2><%= pluralize(@post.errors.count, "error") %> prohibited
       this post from being saved:</h2>
     <ul>
@@ -941,7 +948,7 @@ appear next to the "Show" link:
   <tr>
     <td><%= post.title %></td>
     <td><%= post.text %></td>
-    <td><%= link_to 'Show', post_path %></td>
+    <td><%= link_to 'Show', post %></td>
     <td><%= link_to 'Edit', edit_post_path(post) %></td>
   </tr>
 <% end %>
@@ -979,7 +986,7 @@ content:
 ```html+erb
 <%= form_for @post do |f| %>
   <% if @post.errors.any? %>
-  <div id="errorExplanation">
+  <div id="error_explanation">
     <h2><%= pluralize(@post.errors.count, "error") %> prohibited
       this post from being saved:</h2>
     <ul>
@@ -1083,7 +1090,7 @@ together.
   <tr>
     <td><%= post.title %></td>
     <td><%= post.text %></td>
-    <td><%= link_to 'Show', post_path %></td>
+    <td><%= link_to 'Show', post_path(post) %></td>
     <td><%= link_to 'Edit', edit_post_path(post) %></td>
     <td><%= link_to 'Destroy', post_path(post),
                     method: :delete, data: { confirm: 'Are you sure?' } %></td>
@@ -1092,7 +1099,7 @@ together.
 </table>
 ```
 
-Here we're using `link_to` in a different way. We pass the named route as the first argument, 
+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'`
 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`.
@@ -1103,7 +1110,7 @@ generated the application. Without this file, the confirmation dialog box wouldn
 ![Confirm Dialog](images/getting_started/confirm_dialog.png)
 
 Congratulations, you can now create, show, list, update and destroy
-posts. 
+posts.
 
 TIP: In general, Rails encourages the use of resources objects in place
 of declaring routes manually.
@@ -1297,8 +1304,8 @@ So first, we'll wire up the Post show template
   </p>
 <% end %>
 
-<%= link_to 'Edit Post', edit_post_path(@post) %> |
-<%= link_to 'Back to Posts', posts_path %>
+<%= link_to 'Back', posts_path %>
+| <%= link_to 'Edit', edit_post_path(@post) %>
 ```
 
 This adds a form on the `Post` show page that creates a new comment by

data/guides/source/i18n.md

@@ -92,7 +92,7 @@ en:
   hello: "Hello world"
 ```
 
-This means, that in the `:en` locale, the key _hello_ will map to the _Hello world_ string. Every string inside Rails is internationalized in this way, see for instance Active Record validation messages in the [`activerecord/lib/active_record/locale/en.yml`](https://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml file or time and date formats in the [`activesupport/lib/active_support/locale/en.yml`](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml) file. You can use YAML or standard Ruby Hashes to store translations in the default (Simple) backend.
+This means, that in the `:en` locale, the key _hello_ will map to the _Hello world_ string. Every string inside Rails is internationalized in this way, see for instance Active Model validation messages in the [`activemodel/lib/active_model/locale/en.yml`](https://github.com/rails/rails/blob/master/activemodel/lib/active_model/locale/en.yml) file or time and date formats in the [`activesupport/lib/active_support/locale/en.yml`](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml) file. You can use YAML or standard Ruby Hashes to store translations in the default (Simple) backend.
 
 The I18n library will use **English** as a **default locale**, i.e. if you don't set a different locale, `:en` will be used for looking up translations.
 
@@ -132,7 +132,7 @@ If you want to translate your Rails application to a **single language other tha
 
 However, you would probably like to **provide support for more locales** in your application. In such case, you need to set and pass the locale between requests.
 
-WARNING: You may be tempted to store the chosen locale in a _session_ or a <em>cookie</em>, however **do not do this**. The locale should be transparent and a part of the URL. This way you won't break people's basic assumptions about the web itself: if you send a URL to a friend, they should see the same page and content as you. A fancy word for this would be that you're being [<em>RESTful</em>](http://en.wikipedia.org/wiki/Representational_State_Transfer. Read more about the RESTful approach in [Stefan Tilkov's articles](http://www.infoq.com/articles/rest-introduction). Sometimes there are exceptions to this rule and those are discussed below.
+WARNING: You may be tempted to store the chosen locale in a _session_ or a <em>cookie</em>, however **do not do this**. The locale should be transparent and a part of the URL. This way you won't break people's basic assumptions about the web itself: if you send a URL to a friend, they should see the same page and content as you. A fancy word for this would be that you're being [<em>RESTful</em>](http://en.wikipedia.org/wiki/Representational_State_Transfer). Read more about the RESTful approach in [Stefan Tilkov's articles](http://www.infoq.com/articles/rest-introduction). Sometimes there are exceptions to this rule and those are discussed below.
 
 The _setting part_ is easy. You can set the locale in a `before_action` in the `ApplicationController` like this:
 
@@ -253,7 +253,7 @@ You would probably need to map URLs like these:
 
 ```ruby
 # config/routes.rb
-match '/:locale' => 'dashboard#index'
+get '/:locale' => 'dashboard#index'
 ```
 
 Do take special care about the **order of your routes**, so this route declaration does not "eat" other ones. (You may want to add it directly before the `root :to` declaration.)
@@ -417,7 +417,7 @@ So that would give you:
 
 ![rails i18n demo localized time to pirate](images/i18n/demo_localized_pirate.png)
 
-TIP: Right now you might need to add some more date/time formats in order to make the I18n backend work as expected (at least for the 'pirate' locale). Of course, there's a great chance that somebody already did all the work by **translating Rails' defaults for your locale**. See the [rails-i18n repository at Github](https://github.com/svenfuchs/rails-i18n/tree/master/rails/locale) for an archive of various locale files. When you put such file(s) in `config/locales/` directory, they will automatically be ready for use.
+TIP: Right now you might need to add some more date/time formats in order to make the I18n backend work as expected (at least for the 'pirate' locale). Of course, there's a great chance that somebody already did all the work by **translating Rails' defaults for your locale**. See the [rails-i18n repository at GitHub](https://github.com/svenfuchs/rails-i18n/tree/master/rails/locale) for an archive of various locale files. When you put such file(s) in `config/locales/` directory, they will automatically be ready for use.
 
 ### Inflection Rules For Other Locales
 
@@ -813,6 +813,7 @@ So, for example, instead of the default error message `"can not be blank"` you c
 | numericality | :equal_to                 | :equal_to                 | count         |
 | numericality | :less_than                | :less_than                | count         |
 | numericality | :less_than_or_equal_to    | :less_than_or_equal_to    | count         |
+| numericality | :only_integer             | :not_an_integer           | -             |
 | numericality | :odd                      | :odd                      | -             |
 | numericality | :even                     | :even                     | -             |
 
@@ -980,8 +981,8 @@ Resources
 
 * [rails-i18n.org](http://rails-i18n.org) - Homepage of the rails-i18n project. You can find lots of useful resources on the [wiki](http://rails-i18n.org/wiki).
 * [Google group: rails-i18n](http://groups.google.com/group/rails-i18n) - The project's mailing list.
-* [Github: rails-i18n](https://github.com/svenfuchs/rails-i18n/tree/master) - Code repository for the rails-i18n project. Most importantly you can find lots of [example translations](https://github.com/svenfuchs/rails-i18n/tree/master/rails/locale) for Rails that should work for your application in most cases.
-* [Github: i18n](https://github.com/svenfuchs/i18n/tree/master) - Code repository for the i18n gem.
+* [GitHub: rails-i18n](https://github.com/svenfuchs/rails-i18n/tree/master) - Code repository for the rails-i18n project. Most importantly you can find lots of [example translations](https://github.com/svenfuchs/rails-i18n/tree/master/rails/locale) for Rails that should work for your application in most cases.
+* [GitHub: i18n](https://github.com/svenfuchs/i18n/tree/master) - Code repository for the i18n gem.
 * [Lighthouse: rails-i18n](http://i18n.lighthouseapp.com/projects/14948-rails-i18n/overview) - Issue tracker for the rails-i18n project.
 * [Lighthouse: i18n](http://i18n.lighthouseapp.com/projects/14947-ruby-i18n/overview) - Issue tracker for the i18n gem.
 

data/guides/source/layout.html.erb

@@ -101,17 +101,15 @@
           You're encouraged to help improve the quality of this guide.
         </p>
         <p>
-          If you see any typos or factual errors you are confident to
-          patch, please clone the <%= link_to 'rails', 'https://github.com/rails/rails' %>
-          repository and open a new pull request. You can also ask for commit rights on
-          <%= link_to 'docrails', 'https://github.com/rails/docrails' %> if you plan to submit
-          several patches. Commits are reviewed, but that happens after you've submitted your
-          contribution. This repository is cross-merged with master periodically.
+          Please contribute if you see any typos or factual errors.
+          To get started, you can read our <%= link_to 'documentation contributions', 'http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation' %> section.
         </p>
         <p>
           You may also find incomplete content, or stuff that is not up to date.
-          Please do add any missing documentation for master. Check the
-          <%= link_to 'Ruby on Rails Guides Guidelines', 'ruby_on_rails_guides_guidelines.html' %>
+          Please do add any missing documentation for master. Make sure to check
+          <%= link_to 'Edge Guides','http://edgeguides.rubyonrails.org' %> first to verify
+          if the issues are already fixed or not on the master branch.
+          Check the <%= link_to 'Ruby on Rails Guides Guidelines', 'ruby_on_rails_guides_guidelines.html' %>
           for style and conventions.
         </p>
         <p>

data/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

data/guides/source/maintenance_policy.md

@@ -0,0 +1,56 @@
+Maintenance Policy for Ruby on Rails
+====================================
+
+Support of the Rails framework is divided into four groups: New features, bug
+fixes, security issues, and severe security issues. They are handled as
+follows, all versions in x.y.z format
+
+--------------------------------------------------------------------------------
+
+New Features
+------------
+
+New features are only added to the master branch and will not be made available
+in point releases.
+
+Bug Fixes
+---------
+
+Only the latest release series will receive bug fixes. When enough bugs are
+fixed and its deemed worthy to release a new gem, this is the branch it happens
+from.
+
+**Currently included series:** 4.0.z
+
+Security Issues
+---------------
+
+The current release series and the next most recent one will receive patches
+and new versions in case of a security issue.
+
+These releases are created by taking the last released version, applying the
+security patches, and releasing. Those patches are then applied to the end of
+the x-y-stable branch. For example, a theoretical 1.2.3 security release would
+be built from 1.2.2, and then added to the end of 1-2-stable. This means that
+security releases are easy to upgrade to if you're running the latest version
+of Rails.
+
+**Currently included series:** 4.0.z, 3.2.z
+
+Severe Security Issues
+----------------------
+
+For severe security issues we will provide new versions as above, and also the
+last major release series will receive patches and new versions. The
+classification of the security issue is judged by the core team.
+
+**Currently included series:** 4.0.z, 3.2.z
+
+Unsupported Release Series
+--------------------------
+
+When a release series is no longer supported, it's your own responsibility to
+deal with bugs and security issues. We may provide backports of the fixes and
+publish them to git, however there will be no new versions released. If you are
+not comfortable maintaining your own versions, you should upgrade to a
+supported version.

data/guides/source/migrations.md

@@ -301,6 +301,7 @@ braces. You can use the following modifiers:
 * `precision`    Defines the precision for the `decimal` fields
 * `scale`        Defines the scale for the `decimal` fields
 * `polymorphic`  Adds a `type` column for `belongs_to` associations
+* `null`         Allows or disallows `NULL` values in the column.
 
 For instance, running
 
@@ -313,8 +314,8 @@ will produce a migration that looks like this
 ```ruby
 class AddDetailsToProducts < ActiveRecord::Migration
   def change
-    add_column :products, :price, precision: 5, scale: 2
-    add_reference :products, :user, polymorphic: true, index: true
+    add_column :products, :price, :decimal, precision: 5, scale: 2
+    add_reference :products, :supplier, polymorphic: true, index: true
   end
 end
 ```
@@ -368,7 +369,7 @@ which creates a `categories_products` table with two columns called
 `category_id` and `product_id`. These columns have the option `:null` set to
 `false` by default.
 
-You can pass the option `:table_name` with you want to customize the table
+You can pass the option `:table_name` when you want to customize the table
 name. For example,
 
 ```ruby
@@ -831,8 +832,7 @@ which contains a `Product` model:
 Bob goes on vacation.
 
 Alice creates a migration for the `products` table which adds a new column and
-initializes it. She also adds a validation to the `Product` model for the new
-column.
+initializes it:
 
 ```ruby
 # db/migrate/20100513121110_add_flag_to_product.rb
@@ -843,11 +843,12 @@ class AddFlagToProduct < ActiveRecord::Migration
     reversible do |dir|
       dir.up { Product.update_all flag: false }
     end
-    Product.update_all flag: false
   end
 end
 ```
 
+She also adds a validation to the `Product` model for the new column:
+
 ```ruby
 # app/models/product.rb
 
@@ -856,9 +857,8 @@ class Product < ActiveRecord::Base
 end
 ```
 
-Alice adds a second migration which adds and initializes another column to the
-`products` table and also adds a validation to the `Product` model for the new
-column.
+Alice adds a second migration which adds another column to the `products`
+table and initializes it:
 
 ```ruby
 # db/migrate/20100515121110_add_fuzz_to_product.rb
@@ -873,6 +873,8 @@ class AddFuzzToProduct < ActiveRecord::Migration
 end
 ```
 
+She also adds a validation to the `Product` model for the new column:
+
 ```ruby
 # app/models/product.rb
 
@@ -905,7 +907,7 @@ A fix for this is to create a local model within the migration. This keeps
 Rails from running the validations, so that the migrations run to completion.
 
 When using a local model, it's a good idea to call
-`Product.reset_column_information` to refresh the `ActiveRecord` cache for the
+`Product.reset_column_information` to refresh the Active Record cache for the
 `Product` model prior to updating data in the database.
 
 If Alice had done this instead, there would have been no problem:
@@ -958,7 +960,7 @@ other product attributes.
 These migrations run just fine, but when Bob comes back from his vacation
 and calls `rake db:migrate` to run all the outstanding migrations, he gets a
 subtle bug: The descriptions have defaults, and the `fuzz` column is present,
-but `fuzz` is nil on all products.
+but `fuzz` is `nil` on all products.
 
 The solution is again to use `Product.reset_column_information` before
 referencing the Product model in a migration, ensuring the Active Record's