rails 4.0.0 → 4.0.1.rc1

data/guides/rails_guides.rb

@@ -22,7 +22,7 @@ end
 
 begin
   require 'redcarpet'
-rescue Gem::LoadError
+rescue LoadError
   # This can happen if doc:guides is executed in an application.
   $stderr.puts('Generating guides requires Redcarpet 2.1.1+.')
   $stderr.puts(<<ERROR) if bundler?
@@ -39,6 +39,25 @@ ERROR
   exit 1
 end
 
+begin
+  require 'nokogiri'
+rescue LoadError
+  # This can happen if doc:guides is executed in an application.
+  $stderr.puts('Generating guides requires Nokogiri.')
+  $stderr.puts(<<ERROR) if bundler?
+Please add
+
+  gem 'nokogiri'
+
+to the Gemfile, run
+
+  bundle install
+
+and try again.
+ERROR
+  exit 1
+end
+
 require 'rails_guides/markdown'
 require "rails_guides/generator"
 RailsGuides::Generator.new.generate

data/guides/source/3_0_release_notes.md

@@ -73,8 +73,6 @@ You can see an example of how that works at [Rails Upgrade is now an Official Pl
 
 Aside from Rails Upgrade tool, if you need more help, there are people on IRC and [rubyonrails-talk](http://groups.google.com/group/rubyonrails-talk) that are probably doing the same thing, possibly hitting the same issues. Be sure to blog your own experiences when upgrading so others can benefit from your knowledge!
 
-More information - [The Path to Rails 3: Approaching the upgrade](http://omgbloglol.com/post/353978923/the-path-to-rails-3-approaching-the-upgrade)
-
 Creating a Rails 3.0 application
 --------------------------------
 

data/guides/source/4_0_release_notes.md

@@ -52,22 +52,22 @@ Major Features
 
 TODO. Give a list and then talk about each of them briefly. We can point to relevant code commits or documentation from these sections.
 
-![Rails 4.0](images/rails4_features.png)
+[![Rails 4.0](images/rails4_features.png)](http://guides.rubyonrails.org/images/rails4_features.png)
 
 Extraction of features to gems
 ---------------------------
 
 In Rails 4.0, several features have been extracted into gems. You can simply add the extracted gems to your `Gemfile` to bring the functionality back.
 
-* Hash-based & Dynamic finder methods ([Github](https://github.com/rails/activerecord-deprecated_finders))
-* Mass assignment protection in Active Record models ([Github](https://github.com/rails/protected_attributes), [Pull Request](https://github.com/rails/rails/pull/7251))
-* ActiveRecord::SessionStore ([Github](https://github.com/rails/activerecord-session_store), [Pull Request](https://github.com/rails/rails/pull/7436))
-* Active Record Observers ([Github](https://github.com/rails/rails-observers), [Commit](https://github.com/rails/rails/commit/39e85b3b90c58449164673909a6f1893cba290b2))
-* Active Resource ([Github](https://github.com/rails/activeresource), [Pull Request](https://github.com/rails/rails/pull/572), [Blog](http://yetimedia.tumblr.com/post/35233051627/activeresource-is-dead-long-live-activeresource))
-* Action Caching ([Github](https://github.com/rails/actionpack-action_caching), [Pull Request](https://github.com/rails/rails/pull/7833))
-* Page Caching ([Github](https://github.com/rails/actionpack-page_caching), [Pull Request](https://github.com/rails/rails/pull/7833))
-* Sprockets ([Github](https://github.com/rails/sprockets-rails))
-* Performance tests ([Github](https://github.com/rails/rails-perftest), [Pull Request](https://github.com/rails/rails/pull/8876))
+* Hash-based & Dynamic finder methods ([GitHub](https://github.com/rails/activerecord-deprecated_finders))
+* Mass assignment protection in Active Record models ([GitHub](https://github.com/rails/protected_attributes), [Pull Request](https://github.com/rails/rails/pull/7251))
+* ActiveRecord::SessionStore ([GitHub](https://github.com/rails/activerecord-session_store), [Pull Request](https://github.com/rails/rails/pull/7436))
+* Active Record Observers ([GitHub](https://github.com/rails/rails-observers), [Commit](https://github.com/rails/rails/commit/39e85b3b90c58449164673909a6f1893cba290b2))
+* Active Resource ([GitHub](https://github.com/rails/activeresource), [Pull Request](https://github.com/rails/rails/pull/572), [Blog](http://yetimedia.tumblr.com/post/35233051627/activeresource-is-dead-long-live-activeresource))
+* Action Caching ([GitHub](https://github.com/rails/actionpack-action_caching), [Pull Request](https://github.com/rails/rails/pull/7833))
+* Page Caching ([GitHub](https://github.com/rails/actionpack-page_caching), [Pull Request](https://github.com/rails/rails/pull/7833))
+* Sprockets ([GitHub](https://github.com/rails/sprockets-rails))
+* Performance tests ([GitHub](https://github.com/rails/rails-perftest), [Pull Request](https://github.com/rails/rails/pull/8876))
 
 Documentation
 -------------
@@ -89,6 +89,10 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railt
 
 * Threadsafe on by default
 
+* Ability to use a custom builder by passing `--builder` (or `-b`) to
+  `rails new` has been removed. Consider using application templates
+  instead. ([Pull Request](https://github.com/rails/rails/pull/9401))
+
 ### Deprecations
 
 * `config.threadsafe!` is deprecated in favor of `config.eager_load` which provides a more fine grained control on what is eager loaded.
@@ -133,17 +137,30 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/activ
 
 *   `Object#try` will now return nil instead of raise a NoMethodError if the receiving object does not implement the method, but you can still get the old behavior by using the new `Object#try!`.
 
+* `String#to_date` now raises `Argument Error: invalid date` instead of `NoMethodError: undefined method 'div' for nil:NilClass`
+  when given an invalid date. It is now the same as `Date.parse`, and it accepts more invalid dates than 3.x, such as:
+
+  ```
+  # ActiveSupport 3.x
+  "asdf".to_date # => NoMethodError: undefined method `div' for nil:NilClass
+  "333".to_date # => NoMethodError: undefined method `div' for nil:NilClass
+
+  # ActiveSupport 4
+  "asdf".to_date # => ArgumentError: invalid date
+  "333".to_date # => Fri, 29 Nov 2013
+  ```
+
 ### Deprecations
 
 *   Deprecate `ActiveSupport::TestCase#pending` method, use `skip` from MiniTest instead.
 
-*   ActiveSupport::Benchmarkable#silence has been deprecated due to its lack of thread safety. It will be removed without replacement in Rails 4.1.
+*   `ActiveSupport::Benchmarkable#silence` has been deprecated due to its lack of thread safety. It will be removed without replacement in Rails 4.1.
 
 *   `ActiveSupport::JSON::Variable` is deprecated. Define your own `#as_json` and `#encode_json` methods for custom JSON string literals.
 
-*   Deprecates the compatibility method Module#local_constant_names, use Module#local_constants instead (which returns symbols).
+*   Deprecates the compatibility method `Module#local_constant_names`, use `Module#local_constants` instead (which returns symbols).
 
-*   BufferedLogger is deprecated.  Use ActiveSupport::Logger, or the logger from Ruby standard library.
+*   `BufferedLogger` is deprecated. Use `ActiveSupport::Logger`, or the logger from Ruby standard library.
 
 *   Deprecate `assert_present` and `assert_blank` in favor of `assert object.blank?` and `assert object.present?`
 

data/guides/source/_welcome.html.erb

@@ -10,10 +10,13 @@
 </p>
 <% else %>
 <p>
-  These are the new guides for Rails 3.2 based on <a href="https://github.com/rails/rails/tree/<%= @version %>"><%= @version %></a>.
+  These are the new guides for Rails 4.0 based on <a href="https://github.com/rails/rails/tree/<%= @version %>"><%= @version %></a>.
   These guides are designed to make you immediately productive with Rails, and to help you understand how all of the pieces fit together.
 </p>
 <% end %>
+<p>
+  The guides for Rails 3.2.x are available at <a href="http://guides.rubyonrails.org/v3.2.14/">http://guides.rubyonrails.org/v3.2.14/</a>.
+</p>
 <p>
   The guides for Rails 2.3.x are available at <a href="http://guides.rubyonrails.org/v2.3.11/">http://guides.rubyonrails.org/v2.3.11/</a>.
 </p>

data/guides/source/action_controller_overview.md

@@ -160,7 +160,7 @@ NOTE: Support for parsing XML parameters has been extracted into a gem named `ac
 The `params` hash will always contain the `:controller` and `:action` keys, but you should use the methods `controller_name` and `action_name` instead to access these values. Any other parameters defined by the routing, such as `:id` will also be available. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the `:status` parameter in a "pretty" URL:
 
 ```ruby
-match '/clients/:status' => 'clients#index', foo: 'bar'
+get '/clients/:status' => 'clients#index', foo: 'bar'
 ```
 
 In this case, when a user opens the URL `/clients/active`, `params[:status]` will be set to "active". When this route is used, `params[:foo]` will also be set to "bar" just like it was passed in the query string. In the same way `params[:action]` will contain "index".
@@ -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
 ```

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

data/guides/source/action_view_overview.md

@@ -269,7 +269,7 @@ Rails will render the `_product_ruler` partial (with no data passed to it) betwe
 
 ### Layouts
 
-Layouts can be used to render a common view template around the results of Rails controller actions. Typically, every Rails has a couple of overall layouts that most pages are rendered within. For example, a site might have a layout for a logged in user, and a layout for the marketing or sales side of the site. The logged in user layout might include top-level navigation that should be present across many controller actions. The sales layout for a SaaS app might include top-level navigation for things like "Pricing" and "Contact Us." You would expect each layout to have a different look and feel. You can read more details about Layouts in the [Layouts and Rendering in Rails](layouts_and_rendering.html) guide.
+Layouts can be used to render a common view template around the results of Rails controller actions. Typically, every Rails application has a couple of overall layouts that most pages are rendered within. For example, a site might have a layout for a logged in user, and a layout for the marketing or sales side of the site. The logged in user layout might include top-level navigation that should be present across many controller actions. The sales layout for a SaaS app might include top-level navigation for things like "Pricing" and "Contact Us." You would expect each layout to have a different look and feel. You can read more details about Layouts in the [Layouts and Rendering in Rails](layouts_and_rendering.html) guide.
 
 Partial Layouts
 ---------------
@@ -1090,7 +1090,7 @@ Example object structure for use with this method:
 
 ```ruby
 class Post < ActiveRecord::Base
-  has_and_belongs_to_many :author
+  has_and_belongs_to_many :authors
 end
 
 class Author < ActiveRecord::Base
@@ -1489,72 +1489,3 @@ end
 Then you could create special views like `app/views/posts/show.expert.html.erb` that would only be displayed to expert users.
 
 You can read more about the Rails Internationalization (I18n) API [here](i18n.html).
-
-Using Action View outside of Rails
-----------------------------------
-
-Action View is a Rails component, but it can also be used without Rails. We can demonstrate this by creating a small [Rack](http://rack.rubyforge.org/) application that includes Action View functionality. This may be useful, for example, if you'd like access to Action View's helpers in a Rack application.
-
-Let's start by ensuring that you have the Action Pack and Rack gems installed:
-
-```bash
-$ gem install actionpack
-$ gem install rack
-```
-
-Now we'll create a simple "Hello World" application that uses the `titleize` method provided by Active Support.
-
-**hello_world.rb:**
-
-```ruby
-require 'active_support/core_ext/string/inflections'
-require 'rack'
-
-def hello_world(env)
-  [200, {"Content-Type" => "text/html"}, "hello world".titleize]
-end
-
-Rack::Handler::Mongrel.run method(:hello_world), Port: 4567
-```
-
-We can see this all come together by starting up the application and then visiting `http://localhost:4567/`
-
-```bash
-$ ruby hello_world.rb
-```
-
-TODO needs a screenshot? I have one - not sure where to put it.
-
-Notice how 'hello world' has been converted into 'Hello World' by the `titleize` helper method.
-
-Action View can also be used with [Sinatra](http://www.sinatrarb.com/) in the same way.
-
-Let's start by ensuring that you have the Action Pack and Sinatra gems installed:
-
-```bash
-$ gem install actionpack
-$ gem install sinatra
-```
-
-Now we'll create the same "Hello World" application in Sinatra.
-
-**hello_world.rb:**
-
-```ruby
-require 'action_view'
-require 'sinatra'
-
-get '/' do
-  erb 'hello world'.titleize
-end
-```
-
-Then, we can run the application:
-
-```bash
-$ ruby hello_world.rb
-```
-
-Once the application is running, you can see Sinatra and Action View working together by visiting `http://localhost:4567/`
-
-TODO needs a screenshot? I have one - not sure where to put it.

data/guides/source/active_record_basics.md

@@ -105,7 +105,7 @@ depending on the purpose of these columns.
   Migrations](migrations.html) to create your tables, this column will be
   automatically created.
 
-There are also some optional column names that will create additional features
+There are also some optional column names that will add additional features
 to Active Record instances:
 
 * `created_at` - Automatically gets set to the current date and time when the
@@ -116,7 +116,7 @@ to Active Record instances:
   locking](http://api.rubyonrails.org/classes/ActiveRecord/Locking.html) to
   a model.
 * `type` - Specifies that the model uses [Single Table
-  Inheritance](http://api.rubyonrails.org/classes/ActiveRecord/Base.html)
+  Inheritance](http://api.rubyonrails.org/classes/ActiveRecord/Base.html#label-Single+table+inheritance).
 * `(association_name)_type` - Stores the type for
   [polymorphic associations](association_basics.html#polymorphic-associations).
 * `(table_name)_count` - Used to cache the number of belonging objects on
@@ -188,11 +188,11 @@ end
 ```
 
 It's also possible to override the column that should be used as the table's
-primary key using the `ActiveRecord::Base.set_primary_key` method:
+primary key using the `ActiveRecord::Base.primary_key=` method:
 
 ```ruby
 class Product < ActiveRecord::Base
-  set_primary_key "product_id"
+  self.primary_key = "product_id"
 end
 ```
 
@@ -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
 ```
 
@@ -343,7 +343,7 @@ Migrations
 
 Rails provides a domain-specific language for managing a database schema called
 migrations. Migrations are stored in files which are executed against any
-database that Active Record support using `rake`. Here's a migration that
+database that Active Record supports using `rake`. Here's a migration that
 creates a table:
 
 ```ruby

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

data/guides/source/active_record_querying.md

@@ -524,12 +524,18 @@ To retrieve records from the database in a specific order, you can use the `orde
 For example, if you're getting a set of records and want to order them in ascending order by the `created_at` field in your table:
 
 ```ruby
+Client.order(:created_at)
+# OR
 Client.order("created_at")
 ```
 
 You could specify `ASC` or `DESC` as well:
 
 ```ruby
+Client.order(created_at: :desc)
+# OR
+Client.order(created_at: :asc)
+# OR
 Client.order("created_at DESC")
 # OR
 Client.order("created_at ASC")
@@ -538,16 +544,20 @@ Client.order("created_at ASC")
 Or ordering by multiple fields:
 
 ```ruby
+Client.order(orders_count: :asc, created_at: :desc)
+# OR
+Client.order(:orders_count, created_at: :desc)
+# OR
 Client.order("orders_count ASC, created_at DESC")
 # OR
 Client.order("orders_count ASC", "created_at DESC")
 ```
 
-If you want to call `order` multiple times e.g. in different context, new order will prepend previous one
+If you want to call `order` multiple times e.g. in different context, new order will append previous one
 
 ```ruby
 Client.order("orders_count ASC").order("created_at DESC")
-# SELECT * FROM clients ORDER BY created_at DESC, orders_count ASC
+# SELECT * FROM clients ORDER BY orders_count ASC, created_at DESC
 ```
 
 Selecting Specific Fields
@@ -1203,7 +1213,6 @@ class User < ActiveRecord::Base
   scope :inactive, -> { where state: 'inactive' }
 end
 
-```ruby
 User.active.inactive
 # => SELECT "users".* FROM "users" WHERE "users"."state" = 'active' AND "users"."state" = 'inactive'
 ```
@@ -1449,7 +1458,7 @@ Client.pluck(:id, :name)
 # => [[1, 'David'], [2, 'Jeremy'], [3, 'Jose']]
 ```
 
-`pluck` makes it possible to replace code like
+`pluck` makes it possible to replace code like:
 
 ```ruby
 Client.select(:id).map { |c| c.id }
@@ -1459,7 +1468,7 @@ Client.select(:id).map(&:id)
 Client.select(:id, :name).map { |c| [c.id, c.name] }
 ```
 
-with
+with:
 
 ```ruby
 Client.pluck(:id)
@@ -1467,6 +1476,37 @@ Client.pluck(:id)
 Client.pluck(:id, :name)
 ```
 
+Unlike `select`, `pluck` directly converts a database result into a Ruby `Array`,
+without constructing `ActiveRecord` objects. This can mean better performance for
+a large or often-running query. However, any model method overrides will
+not be available. For example:
+
+```ruby
+class Client < ActiveRecord::Base
+  def name
+    "I am #{super}"
+  end
+end
+
+Client.select(:name).map &:name
+# => ["I am David", "I am Jeremy", "I am Jose"]
+
+Client.pluck(:name)
+# => ["David", "Jeremy", "Jose"]
+```
+
+Furthermore, unlike `select` and other `Relation` scopes, `pluck` triggers an immediate
+query, and thus cannot be chained with any further scopes, although it can work with
+scopes already constructed earlier:
+
+```ruby
+Client.pluck(:name).limit(1)
+# => NoMethodError: undefined method `limit' for #<Array:0x007ff34d3ad6d8>
+
+Client.limit(1).pluck(:name)
+# => ["David"]
+```
+
 ### `ids`
 
 `ids` can be used to pluck all the IDs for the relation using the table's primary key.