rails 4.1.4 → 4.2.11.3

data/guides/source/initialization.md

@@ -98,9 +98,9 @@ configure the load path for your Gemfile's dependencies.
 
 A standard Rails application depends on several gems, specifically:
 
-* abstract
 * actionmailer
 * actionpack
+* actionview
 * activemodel
 * activerecord
 * activesupport
@@ -111,7 +111,6 @@ A standard Rails application depends on several gems, specifically:
 * i18n
 * mail
 * mime-types
-* polyglot
 * rack
 * rack-cache
 * rack-mount
@@ -119,9 +118,8 @@ A standard Rails application depends on several gems, specifically:
 * rails
 * railties
 * rake
-* sqlite3-ruby
+* sqlite3
 * thor
-* treetop
 * tzinfo
 
 ### `rails/commands.rb`
@@ -163,9 +161,10 @@ throwing an error message. If the command is valid, a method of the same name
 is called.
 
 ```ruby
-COMMAND_WHITELIST = %(plugin generate destroy console server dbconsole application runner new version help)
+COMMAND_WHITELIST = %w(plugin generate destroy console server dbconsole application runner new version help)
 
 def run_command!(command)
+  command = parse_command(command)
   if COMMAND_WHITELIST.include?(command)
     send(command)
   else
@@ -178,8 +177,7 @@ With the `server` command, Rails will further run the following code:
 
 ```ruby
 def set_application_directory!
-  Dir.chdir(File.expand_path('../../', APP_PATH)) unless
-  File.exist?(File.expand_path("config.ru"))
+  Dir.chdir(File.expand_path('../../', APP_PATH)) unless File.exist?(File.expand_path("config.ru"))
 end
 
 def server
@@ -187,6 +185,8 @@ def server
   require_command!("server")
 
   Rails::Server.new.tap do |server|
+    # We need to require application after the server sets environment,
+    # otherwise the --environment option given to the server won't propagate.
     require APP_PATH
     Dir.chdir(Rails.application.root)
     server.start
@@ -207,6 +207,7 @@ sets up the `Rails::Server` class.
 require 'fileutils'
 require 'optparse'
 require 'action_dispatch'
+require 'rails'
 
 module Rails
   class Server < ::Rack::Server
@@ -273,7 +274,7 @@ def parse_options(args)
   # http://www.meb.uni-bonn.de/docs/cgi/cl.html
   args.clear if ENV.include?("REQUEST_METHOD")
 
-  options.merge! opt_parser.parse! args
+  options.merge! opt_parser.parse!(args)
   options[:config] = ::File.expand_path(options[:config])
   ENV["RACK_ENV"] = options[:environment]
   options
@@ -284,18 +285,21 @@ With the `default_options` set to this:
 
 ```ruby
 def default_options
+  environment  = ENV['RACK_ENV'] || 'development'
+  default_host = environment == 'development' ? 'localhost' : '0.0.0.0'
+
   {
-    environment: ENV['RACK_ENV'] || "development",
-    pid:         nil,
-    Port:        9292,
-    Host:        "0.0.0.0",
-    AccessLog:   [],
-    config:      "config.ru"
+    :environment => environment,
+    :pid         => nil,
+    :Port        => 9292,
+    :Host        => default_host,
+    :AccessLog   => [],
+    :config      => "config.ru"
   }
 end
 ```
 
-There is no `REQUEST_METHOD` key in `ENV` so we can skip over that line. The next line merges in the options from `opt_parser` which is defined plainly in `Rack::Server`
+There is no `REQUEST_METHOD` key in `ENV` so we can skip over that line. The next line merges in the options from `opt_parser` which is defined plainly in `Rack::Server`:
 
 ```ruby
 def opt_parser
@@ -348,6 +352,7 @@ private
   def print_boot_information
     ...
     puts "=> Run `rails server -h` for more startup options"
+    ...
     puts "=> Ctrl-C to shutdown server" unless options[:daemonize]
   end
 
@@ -434,7 +439,11 @@ The `app` method here is defined like so:
 
 ```ruby
 def app
-  @app ||= begin
+  @app ||= options[:builder] ? build_app_from_string : build_app_and_options_from_config
+end
+...
+private
+  def build_app_and_options_from_config
     if !::File.exist? options[:config]
       abort "configuration #{options[:config]} not found"
     end
@@ -443,7 +452,10 @@ def app
     self.options.merge! options
     app
   end
-end
+
+  def build_app_from_string
+    Rack::Builder.new_from_string(self.options[:builder])
+  end
 ```
 
 The `options[:config]` value defaults to `config.ru` which contains this:
@@ -459,8 +471,14 @@ run <%= app_const %>
 The `Rack::Builder.parse_file` method here takes the content from this `config.ru` file and parses it using this code:
 
 ```ruby
-app = eval "Rack::Builder.new {( " + cfgfile + "\n )}.to_app",
-    TOPLEVEL_BINDING, config
+app = new_from_string cfgfile, config
+
+...
+
+def self.new_from_string(builder_script, file="(rackup)")
+  eval "Rack::Builder.new {\n" + builder_script + "\n}.to_app",
+    TOPLEVEL_BINDING, file, 0
+end
 ```
 
 The `initialize` method of `Rack::Builder` will take the block here and execute it within an instance of `Rack::Builder`. This is where the majority of the initialization process of Rails happens. The `require` line for `config/environment.rb` in `config.ru` is the first to run:
@@ -473,11 +491,22 @@ require ::File.expand_path('../config/environment', __FILE__)
 
 This file is the common file required by `config.ru` (`rails server`) and Passenger. This is where these two ways to run the server meet; everything before this point has been Rack and Rails setup.
 
-This file begins with requiring `config/application.rb`.
+This file begins with requiring `config/application.rb`:
+
+```ruby
+require File.expand_path('../application', __FILE__)
+```
 
 ### `config/application.rb`
 
-This file requires `config/boot.rb`, but only if it hasn't been required before, which would be the case in `rails server` but **wouldn't** be the case with Passenger.
+This file requires `config/boot.rb`:
+
+```ruby
+require File.expand_path('../boot', __FILE__)
+```
+
+But only if it hasn't been required before, which would be the case in `rails server`
+but **wouldn't** be the case with Passenger.
 
 Then the fun begins!
 
@@ -498,11 +527,12 @@ This file is responsible for requiring all the individual frameworks of Rails:
 require "rails"
 
 %w(
-    active_record
-    action_controller
-    action_mailer
-    rails/test_unit
-    sprockets
+  active_record
+  action_controller
+  action_view
+  action_mailer
+  rails/test_unit
+  sprockets
 ).each do |framework|
   begin
     require "#{framework}/railtie"
@@ -526,8 +556,8 @@ The rest of `config/application.rb` defines the configuration for the
 initialized. When `config/application.rb` has finished loading Rails and defined
 the application namespace, we go back to `config/environment.rb`,
 where the application is initialized. For example, if the application was called
-`Blog`, here we would find `Blog::Application.initialize!`, which is
-defined in `rails/application.rb`
+`Blog`, here we would find `Rails.application.initialize!`, which is
+defined in `rails/application.rb`.
 
 ### `railties/lib/rails/application.rb`
 
@@ -543,7 +573,7 @@ end
 ```
 
 As you can see, you can only initialize an app once. The initializers are run through
-the `run_initializers` method which is defined in `railties/lib/rails/initializable.rb`
+the `run_initializers` method which is defined in `railties/lib/rails/initializable.rb`:
 
 ```ruby
 def run_initializers(group=:default, *args)
@@ -555,7 +585,7 @@ def run_initializers(group=:default, *args)
 end
 ```
 
-The run_initializers code itself is tricky. What Rails is doing here is
+The `run_initializers` code itself is tricky. What Rails is doing here is
 traversing all the class ancestors looking for those that respond to an
 `initializers` method. It then sorts the ancestors by name, and runs them.
 For example, the `Engine` class will make all the engines available by
@@ -568,7 +598,7 @@ initializers (like building the middleware stack) are run last. The `railtie`
 initializers are the initializers which have been defined on the `Rails::Application`
 itself and are run between the `bootstrap` and `finishers`.
 
-After this is done we go back to `Rack::Server`
+After this is done we go back to `Rack::Server`.
 
 ### Rack: lib/rack/server.rb
 
@@ -576,7 +606,11 @@ Last time we left when the `app` method was being defined:
 
 ```ruby
 def app
-  @app ||= begin
+  @app ||= options[:builder] ? build_app_from_string : build_app_and_options_from_config
+end
+...
+private
+  def build_app_and_options_from_config
     if !::File.exist? options[:config]
       abort "configuration #{options[:config]} not found"
     end
@@ -585,7 +619,10 @@ def app
     self.options.merge! options
     app
   end
-end
+
+  def build_app_from_string
+    Rack::Builder.new_from_string(self.options[:builder])
+  end
 ```
 
 At this point `app` is the Rails app itself (a middleware), and what
@@ -603,7 +640,7 @@ def build_app(app)
 end
 ```
 
-Remember, `build_app` was called (by wrapped_app) in the last line of `Server#start`.
+Remember, `build_app` was called (by `wrapped_app`) in the last line of `Server#start`.
 Here's how it looked like when we left:
 
 ```ruby
@@ -611,40 +648,50 @@ server.run wrapped_app, options, &blk
 ```
 
 At this point, the implementation of `server.run` will depend on the
-server you're using. For example, if you were using Mongrel, here's what
+server you're using. For example, if you were using Puma, here's what
 the `run` method would look like:
 
 ```ruby
-def self.run(app, options={})
-  server = ::Mongrel::HttpServer.new(
-    options[:Host]           || '0.0.0.0',
-    options[:Port]           || 8080,
-    options[:num_processors] || 950,
-    options[:throttle]       || 0,
-    options[:timeout]        || 60)
-  # Acts like Rack::URLMap, utilizing Mongrel's own path finding methods.
-  # Use is similar to #run, replacing the app argument with a hash of
-  # { path=>app, ... } or an instance of Rack::URLMap.
-  if options[:map]
-    if app.is_a? Hash
-      app.each do |path, appl|
-        path = '/'+path unless path[0] == ?/
-        server.register(path, Rack::Handler::Mongrel.new(appl))
-      end
-    elsif app.is_a? URLMap
-      app.instance_variable_get(:@mapping).each do |(host, path, appl)|
-       next if !host.nil? && !options[:Host].nil? && options[:Host] != host
-       path = '/'+path unless path[0] == ?/
-       server.register(path, Rack::Handler::Mongrel.new(appl))
-      end
-    else
-      raise ArgumentError, "first argument should be a Hash or URLMap"
-    end
-  else
-    server.register('/', Rack::Handler::Mongrel.new(app))
+...
+DEFAULT_OPTIONS = {
+  :Host => '0.0.0.0',
+  :Port => 8080,
+  :Threads => '0:16',
+  :Verbose => false
+}
+
+def self.run(app, options = {})
+  options  = DEFAULT_OPTIONS.merge(options)
+
+  if options[:Verbose]
+    app = Rack::CommonLogger.new(app, STDOUT)
   end
+
+  if options[:environment]
+    ENV['RACK_ENV'] = options[:environment].to_s
+  end
+
+  server   = ::Puma::Server.new(app)
+  min, max = options[:Threads].split(':', 2)
+
+  puts "Puma #{::Puma::Const::PUMA_VERSION} starting..."
+  puts "* Min threads: #{min}, max threads: #{max}"
+  puts "* Environment: #{ENV['RACK_ENV']}"
+  puts "* Listening on tcp://#{options[:Host]}:#{options[:Port]}"
+
+  server.add_tcp_listener options[:Host], options[:Port]
+  server.min_threads = min
+  server.max_threads = max
   yield server if block_given?
-  server.run.join
+
+  begin
+    server.run.join
+  rescue Interrupt
+    puts "* Gracefully stopping, waiting for requests to finish"
+    server.stop(true)
+    puts "* Goodbye!"
+  end
+
 end
 ```
 

data/guides/source/layout.html.erb

@@ -1,5 +1,4 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<!DOCTYPE html>
 
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
@@ -30,15 +29,11 @@
         More Ruby on Rails
       </span>
       <ul class="more-info-links s-hidden">
-        <li class="more-info"><a href="http://rubyonrails.org/">Overview</a></li>
-        <li class="more-info"><a href="http://rubyonrails.org/download">Download</a></li>
-        <li class="more-info"><a href="http://rubyonrails.org/deploy">Deploy</a></li>
-        <li class="more-info"><a href="https://github.com/rails/rails">Code</a></li>
-        <li class="more-info"><a href="http://rubyonrails.org/screencasts">Screencasts</a></li>
-        <li class="more-info"><a href="http://rubyonrails.org/documentation">Documentation</a></li>
-        <li class="more-info"><a href="http://rubyonrails.org/ecosystem">Ecosystem</a></li>
-        <li class="more-info"><a href="http://rubyonrails.org/community">Community</a></li>
         <li class="more-info"><a href="http://weblog.rubyonrails.org/">Blog</a></li>
+        <li class="more-info"><a href="http://guides.rubyonrails.org/">Guides</a></li>
+        <li class="more-info"><a href="http://api.rubyonrails.org/">API</a></li>
+        <li class="more-info"><a href="http://stackoverflow.com/questions/tagged/ruby-on-rails">Ask for help</a></li>
+        <li class="more-info"><a href="https://github.com/rails/rails">Contribute on GitHub</a></li>
       </ul>
     </div>
   </div>
@@ -78,7 +73,6 @@
           </select>
         </li>
       </ul>
-      </div>
     </div>
   </div>
   <hr class="hide" />

data/guides/source/layouts_and_rendering.md

@@ -175,23 +175,22 @@ render template: "products/show"
 
 #### Rendering an Arbitrary File
 
-The `render` method can also use a view that's entirely outside of your application (perhaps you're sharing views between two Rails applications):
-
-```ruby
-render "/u/apps/warehouse_app/current/app/views/products/show"
-```
-
-Rails determines that this is a file render because of the leading slash character. To be explicit, you can use the `:file` option (which was required on Rails 2.2 and earlier):
+The `render` method can also use a view that's entirely outside of your application:
 
 ```ruby
 render file: "/u/apps/warehouse_app/current/app/views/products/show"
 ```
 
-The `:file` option takes an absolute file-system path. Of course, you need to have rights to the view that you're using to render the content.
+The `:file` option takes an absolute file-system path. Of course, you need to have rights
+to the view that you're using to render the content.
+
+NOTE: Using the `:file` option in combination with users input can lead to security problems
+since an attacker could use this action to access security sensitive files in your file system.
 
-NOTE: By default, the file is rendered without using the current layout. If you want Rails to put the file into the current layout, you need to add the `layout: true` option.
+NOTE: By default, the file is rendered using the current layout.
 
-TIP: If you're running Rails on Microsoft Windows, you should use the `:file` option to render a file, because Windows filenames do not have the same format as Unix filenames.
+TIP: If you're running Rails on Microsoft Windows, you should use the `:file` option to
+render a file, because Windows filenames do not have the same format as Unix filenames.
 
 #### Wrapping it up
 
@@ -248,7 +247,8 @@ service requests that are expecting something other than proper HTML.
 
 NOTE: By default, if you use the `:plain` option, the text is rendered without
 using the current layout. If you want Rails to put the text into the current
-layout, you need to add the `layout: true` option.
+layout, you need to add the `layout: true` option and use the `.txt.erb`
+extension for the layout file.
 
 #### Rendering HTML
 
@@ -263,7 +263,7 @@ TIP: This is useful when you're rendering a small snippet of HTML code.
 However, you might want to consider moving it to a template file if the markup
 is complex.
 
-NOTE: This option will escape HTML entities if the string is not html safe.
+NOTE: This option will escape HTML entities if the string is not HTML safe.
 
 #### Rendering JSON
 
@@ -308,7 +308,7 @@ TIP: This option should be used only if you don't care about the content type of
 the response. Using `:plain` or `:html` might be more appropriate in most of the
 time.
 
-NOTE: Unless overriden, your response returned from this render option will be
+NOTE: Unless overridden, your response returned from this render option will be
 `text/html`, as that is the default content type of Action Dispatch response.
 
 #### Options for `render`
@@ -506,33 +506,33 @@ Layout declarations cascade downward in the hierarchy, and more specific layout
     end
     ```
 
-* `posts_controller.rb`
+* `articles_controller.rb`
 
     ```ruby
-    class PostsController < ApplicationController
+    class ArticlesController < ApplicationController
     end
     ```
 
-* `special_posts_controller.rb`
+* `special_articles_controller.rb`
 
     ```ruby
-    class SpecialPostsController < PostsController
+    class SpecialArticlesController < ArticlesController
       layout "special"
     end
     ```
 
-* `old_posts_controller.rb`
+* `old_articles_controller.rb`
 
     ```ruby
-    class OldPostsController < SpecialPostsController
+    class OldArticlesController < SpecialArticlesController
       layout false
 
       def show
-        @post = Post.find(params[:id])
+        @article = Article.find(params[:id])
       end
 
       def index
-        @old_posts = Post.older
+        @old_articles = Article.older
         render layout: "old"
       end
       # ...
@@ -542,10 +542,10 @@ Layout declarations cascade downward in the hierarchy, and more specific layout
 In this application:
 
 * In general, views will be rendered in the `main` layout
-* `PostsController#index` will use the `main` layout
-* `SpecialPostsController#index` will use the `special` layout
-* `OldPostsController#show` will use no layout at all
-* `OldPostsController#index` will use the `old` layout
+* `ArticlesController#index` will use the `main` layout
+* `SpecialArticlesController#index` will use the `special` layout
+* `OldArticlesController#show` will use no layout at all
+* `OldArticlesController#index` will use the `old` layout
 
 #### Avoiding Double Render Errors
 
@@ -903,7 +903,7 @@ You can also specify multiple videos to play by passing an array of videos to th
 This will produce:
 
 ```erb
-<video><source src="trailer.ogg" /><source src="movie.ogg" /></video>
+<video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
 ```
 
 #### Linking to Audio Files with the `audio_tag`

data/guides/source/maintenance_policy.md

@@ -3,10 +3,29 @@ 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
+follows, all versions in `X.Y.Z` format.
 
 --------------------------------------------------------------------------------
 
+Rails follows a shifted version of [semver](http://semver.org/):
+
+**Patch `Z`**
+
+Only bug fixes, no API changes, no new features.
+Except as necessary for security fixes.
+
+**Minor `Y`**
+
+New features, may contain API changes (Serve as major versions of Semver).
+Breaking changes are paired with deprecation notices in the previous minor
+or major release.
+
+**Major `X`**
+
+New features, will likely contain API changes. The difference between Rails'
+minor and major releases is the magnitude of breaking changes, and usually
+reserved for special occasions.
+
 New Features
 ------------
 
@@ -20,7 +39,10 @@ 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.1.z, 4.0.z
+In special situations, where someone from the Core Team agrees to support more series,
+they are included in the list of supported series.
+
+**Currently included series:** `4.2.Z`, `4.1.Z` (Supported by Rafael França).
 
 Security Issues
 ---------------
@@ -35,7 +57,7 @@ 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.1.z, 4.0.z
+**Currently included series:** `4.2.Z`, `4.1.Z`.
 
 Severe Security Issues
 ----------------------
@@ -44,7 +66,7 @@ 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.1.z, 4.0.z, 3.2.z
+**Currently included series:** `4.2.Z`, `4.1.Z`, `3.2.Z`.
 
 Unsupported Release Series
 --------------------------

data/guides/source/nested_model_forms.md

@@ -1,4 +1,4 @@
-Rails nested model forms
+Rails Nested Model Forms
 ========================
 
 Creating a form for a model _and_ its associations can become quite tedious. Therefore Rails provides helpers to assist in dealing with the complexities of generating these forms _and_ the required CRUD operations to create, update, and destroy associations.
@@ -17,9 +17,9 @@ Model setup
 
 To be able to use the nested model functionality in your forms, the model will need to support some basic operations.
 
-First of all, it needs to define a writer method for the attribute that corresponds to the association you are building a nested model form for. The `fields_for` form helper will look for this method to decide whether or not a nested model form should be build.
+First of all, it needs to define a writer method for the attribute that corresponds to the association you are building a nested model form for. The `fields_for` form helper will look for this method to decide whether or not a nested model form should be built.
 
-If the associated object is an array a form builder will be yielded for each object, else only a single form builder will be yielded.
+If the associated object is an array, a form builder will be yielded for each object, else only a single form builder will be yielded.
 
 Consider a Person model with an associated Address. When asked to yield a nested FormBuilder for the `:address` attribute, the `fields_for` form helper will look for a method on the Person instance named `address_attributes=`.
 
@@ -54,6 +54,9 @@ class Person < ActiveRecord::Base
 end
 ```
 
+NOTE: For greater detail on associations see [Active Record Associations](association_basics.html).
+For a complete reference on associations please visit the API documentation for [ActiveRecord::Associations::ClassMethods](http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html).
+
 ### Custom model
 
 As you might have inflected from this explanation, you _don't_ necessarily need an ActiveRecord::Base model to use this functionality. The following examples are sufficient to enable the nested model form behavior:
@@ -220,6 +223,6 @@ As you can see it has generated 2 `project name` inputs, one for each new `proje
 
 You can basically see the `projects_attributes` hash as an array of attribute hashes, one for each model instance.
 
-NOTE: The reason that `fields_for` constructed a form which would result in a hash instead of an array is that it won't work for any forms nested deeper than one level deep.
+NOTE: The reason that `fields_for` constructed a hash instead of an array is that it won't work for any form nested deeper than one level deep.
 
 TIP: You _can_ however pass an array to the writer method generated by `accepts_nested_attributes_for` if you're using plain Ruby or some other API access. See (TODO) for more info and example.