rails 4.0.13 → 4.1.16

data/guides/source/plugins.md

@@ -3,9 +3,9 @@ The Basics of Creating Rails Plugins
 
 A Rails plugin is either an extension or a modification of the core framework. Plugins provide:
 
-* a way for developers to share bleeding-edge ideas without hurting the stable code base
-* a segmented architecture so that units of code can be fixed or updated on their own release schedule
-* an outlet for the core developers so that they don’t have to include every cool new feature under the sun
+* A way for developers to share bleeding-edge ideas without hurting the stable code base.
+* A segmented architecture so that units of code can be fixed or updated on their own release schedule.
+* An outlet for the core developers so that they don't have to include every cool new feature under the sun.
 
 After reading this guide, you will know:
 
@@ -15,7 +15,7 @@ After reading this guide, you will know:
 This guide describes how to build a test-driven plugin that will:
 
 * Extend core Ruby classes like Hash and String.
-* Add methods to ActiveRecord::Base in the tradition of the 'acts_as' plugins.
+* Add methods to `ActiveRecord::Base` in the tradition of the `acts_as` plugins.
 * Give you information about where to put generators in your plugin.
 
 For the purpose of this guide pretend for a moment that you are an avid bird watcher.
@@ -39,16 +39,16 @@ to run integration tests using a dummy Rails application. Create your
 plugin with the command:
 
 ```bash
-$ rails plugin new yaffle
+$ bin/rails plugin new yaffle
 ```
 
 See usage and options by asking for help:
 
 ```bash
-$ rails plugin --help
+$ bin/rails plugin --help
 ```
 
-Testing your newly generated plugin
+Testing Your Newly Generated Plugin
 -----------------------------------
 
 You can navigate to the directory that contains the plugin, run the `bundle install` command
@@ -74,7 +74,7 @@ In this example you will add a method to String named `to_squawk`. To begin, cre
 
 require 'test_helper'
 
-class CoreExtTest < Test::Unit::TestCase
+class CoreExtTest < ActiveSupport::TestCase
   def test_to_squawk_prepends_the_word_squawk
     assert_equal "squawk! Hello World", "Hello World".to_squawk
   end
@@ -92,7 +92,7 @@ Run `rake` to run the test. This test should fail because we haven't implemented
 
 Great - now you are ready to start development.
 
-Then in `lib/yaffle.rb` add `require "yaffle/core_ext"`:
+In `lib/yaffle.rb`, add `require "yaffle/core_ext"`:
 
 ```ruby
 # yaffle/lib/yaffle.rb
@@ -124,7 +124,7 @@ To test that your method does what it says it does, run the unit tests with `rak
 To see this in action, change to the test/dummy directory, fire up a console and start squawking:
 
 ```bash
-$ rails console
+$ bin/rails console
 >> "Hello World".to_squawk
 => "squawk! Hello World"
 ```
@@ -132,8 +132,8 @@ $ rails console
 Add an "acts_as" Method to Active Record
 ----------------------------------------
 
-A common pattern in plugins is to add a method called 'acts_as_something' to models. In this case, you
-want to write a method called 'acts_as_yaffle' that adds a 'squawk' method to your Active Record models.
+A common pattern in plugins is to add a method called `acts_as_something` to models. In this case, you
+want to write a method called `acts_as_yaffle` that adds a `squawk` method to your Active Record models.
 
 To begin, set up your files so that you have:
 
@@ -142,7 +142,7 @@ To begin, set up your files so that you have:
 
 require 'test_helper'
 
-class ActsAsYaffleTest < Test::Unit::TestCase
+class ActsAsYaffleTest < ActiveSupport::TestCase
 end
 ```
 
@@ -168,9 +168,9 @@ end
 
 ### Add a Class Method
 
-This plugin will expect that you've added a method to your model named 'last_squawk'. However, the
-plugin users might have already defined a method on their model named 'last_squawk' that they use
-for something else. This plugin will allow the name to be changed by adding a class method called 'yaffle_text_field'.
+This plugin will expect that you've added a method to your model named `last_squawk`. However, the
+plugin users might have already defined a method on their model named `last_squawk` that they use
+for something else. This plugin will allow the name to be changed by adding a class method called `yaffle_text_field`.
 
 To start out, write a failing test that shows the behavior you'd like:
 
@@ -179,7 +179,7 @@ To start out, write a failing test that shows the behavior you'd like:
 
 require 'test_helper'
 
-class ActsAsYaffleTest < Test::Unit::TestCase
+class ActsAsYaffleTest < ActiveSupport::TestCase
 
   def test_a_hickwalls_yaffle_text_field_should_be_last_squawk
     assert_equal "last_squawk", Hickwall.yaffle_text_field
@@ -214,17 +214,16 @@ test/dummy directory:
 
 ```bash
 $ cd test/dummy
-$ rails generate model Hickwall last_squawk:string
-$ rails generate model Wickwall last_squawk:string last_tweet:string
+$ bin/rails generate model Hickwall last_squawk:string
+$ bin/rails generate model Wickwall last_squawk:string last_tweet:string
 ```
 
 Now you can create the necessary database tables in your testing database by navigating to your dummy app
-and migrating the database. First
+and migrating the database. First, run:
 
 ```bash
 $ cd test/dummy
-$ rake db:migrate
-$ rake db:test:prepare
+$ bin/rake db:migrate
 ```
 
 While you are here, change the Hickwall and Wickwall models so that they know that they are supposed to act
@@ -245,7 +244,7 @@ end
 
 ```
 
-We will also add code to define the acts_as_yaffle method.
+We will also add code to define the `acts_as_yaffle` method.
 
 ```ruby
 # yaffle/lib/yaffle/acts_as_yaffle.rb
@@ -286,7 +285,7 @@ You can then return to the root directory (`cd ../..`) of your plugin and rerun
 
 ```
 
-Getting closer... Now we will implement the code of the acts_as_yaffle method to make the tests pass.
+Getting closer... Now we will implement the code of the `acts_as_yaffle` method to make the tests pass.
 
 ```ruby
 # yaffle/lib/yaffle/acts_as_yaffle.rb
@@ -310,7 +309,7 @@ end
 ActiveRecord::Base.send :include, Yaffle::ActsAsYaffle
 ```
 
-When you run `rake` you should see the tests all pass:
+When you run `rake`, you should see the tests all pass:
 
 ```bash
   5 tests, 5 assertions, 0 failures, 0 errors, 0 skips
@@ -327,7 +326,7 @@ To start out, write a failing test that shows the behavior you'd like:
 # yaffle/test/acts_as_yaffle_test.rb
 require 'test_helper'
 
-class ActsAsYaffleTest < Test::Unit::TestCase
+class ActsAsYaffleTest < ActiveSupport::TestCase
 
   def test_a_hickwalls_yaffle_text_field_should_be_last_squawk
     assert_equal "last_squawk", Hickwall.yaffle_text_field
@@ -390,7 +389,11 @@ Run `rake` one final time and you should see:
   7 tests, 7 assertions, 0 failures, 0 errors, 0 skips
 ```
 
-NOTE: The use of `write_attribute` to write to the field in model is just one example of how a plugin can interact with the model, and will not always be the right method to use. For example, you could also use `send("#{self.class.yaffle_text_field}=", string.to_squawk)`.
+NOTE: The use of `write_attribute` to write to the field in model is just one example of how a plugin can interact with the model, and will not always be the right method to use. For example, you could also use:
+
+```ruby
+send("#{self.class.yaffle_text_field}=", string.to_squawk)
+```
 
 Generators
 ----------
@@ -398,7 +401,7 @@ Generators
 Generators can be included in your gem simply by creating them in a lib/generators directory of your plugin. More information about
 the creation of generators can be found in the [Generators Guide](generators.html)
 
-Publishing your Gem
+Publishing Your Gem
 -------------------
 
 Gem plugins currently in development can easily be shared from any Git repository. To share the Yaffle gem with others, simply
@@ -411,12 +414,12 @@ gem 'yaffle', git: 'git://github.com/yaffle_watcher/yaffle.git'
 After running `bundle install`, your gem functionality will be available to the application.
 
 When the gem is ready to be shared as a formal release, it can be published to [RubyGems](http://www.rubygems.org).
-For more information about publishing gems to RubyGems, see: [Creating and Publishing Your First Ruby Gem](http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html)
+For more information about publishing gems to RubyGems, see: [Creating and Publishing Your First Ruby Gem](http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html).
 
 RDoc Documentation
 ------------------
 
-Once your plugin is stable and you are ready to deploy do everyone else a favor and document it! Luckily, writing documentation for your plugin is easy.
+Once your plugin is stable and you are ready to deploy, do everyone else a favor and document it! Luckily, writing documentation for your plugin is easy.
 
 The first step is to update the README file with detailed information about how to use your plugin. A few key things to include are:
 
@@ -430,7 +433,7 @@ Once your README is solid, go through and add rdoc comments to all of the method
 Once your comments are good to go, navigate to your plugin directory and run:
 
 ```bash
-$ rake rdoc
+$ bin/rake rdoc
 ```
 
 ### References

data/guides/source/rails_application_templates.md

@@ -23,8 +23,8 @@ $ rails new blog -m http://example.com/template.rb
 You can use the rake task `rails:template` to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL.
 
 ```bash
-$ rake rails:template LOCATION=~/template.rb
-$ rake rails:template LOCATION=http://example.com/template.rb
+$ bin/rake rails:template LOCATION=~/template.rb
+$ bin/rake rails:template LOCATION=http://example.com/template.rb
 ```
 
 Template API
@@ -47,7 +47,7 @@ The following sections outline the primary methods provided by the API:
 
 ### gem(*args)
 
-Adds a `gem` entry for the supplied gem to the generated application’s `Gemfile`.
+Adds a `gem` entry for the supplied gem to the generated application's `Gemfile`.
 
 For example, if your application depends on the gems `bj` and `nokogiri`:
 
@@ -91,14 +91,14 @@ Adds a line inside the `Application` class for `config/application.rb`.
 If `options[:env]` is specified, the line is appended to the corresponding file in `config/environments`.
 
 ```ruby
-environment 'config.action_mailer.default_url_options = {host: 'http://yourwebsite.example.com'}, env: 'production'
+environment 'config.action_mailer.default_url_options = {host: "http://yourwebsite.example.com"}', env: 'production'
 ```
 
 A block can be used in place of the `data` argument.
 
 ### vendor/lib/file/initializer(filename, data = nil, &block)
 
-Adds an initializer to the generated application’s `config/initializers` directory.
+Adds an initializer to the generated application's `config/initializers` directory.
 
 Let's say you like using `Object#not_nil?` and `Object#not_blank?`:
 
@@ -127,7 +127,7 @@ file 'app/components/foo.rb', <<-CODE
 CODE
 ```
 
-That’ll create the `app/components` directory and put `foo.rb` in there.
+That'll create the `app/components` directory and put `foo.rb` in there.
 
 ### rakefile(filename, data = nil, &block)
 
@@ -197,7 +197,7 @@ end
 
 ### ask(question)
 
-`ask()` gives you a chance to get some feedback from the user and use it in your templates. Let's say you want your user to name the new shiny library you’re adding:
+`ask()` gives you a chance to get some feedback from the user and use it in your templates. Let's say you want your user to name the new shiny library you're adding:
 
 ```ruby
 lib_name = ask("What do you want to call the shiny library ?")
@@ -211,7 +211,7 @@ CODE
 
 ### yes?(question) or no?(question)
 
-These methods let you ask questions from templates and decide the flow based on the user’s answer. Let's say you want to freeze rails only if the user wants to:
+These methods let you ask questions from templates and decide the flow based on the user's answer. Let's say you want to freeze rails only if the user wants to:
 
 ```ruby
 rake("rails:freeze:gems") if yes?("Freeze rails gems?")
@@ -227,3 +227,22 @@ git :init
 git add: "."
 git commit: "-a -m 'Initial commit'"
 ```
+
+Advanced Usage
+--------------
+
+The application template is evaluated in the context of a
+`Rails::Generators::AppGenerator` instance. It uses the `apply` action
+provided by
+[Thor](https://github.com/erikhuda/thor/blob/master/lib/thor/actions.rb#L207).
+This means you can extend and change the instance to match your needs.
+
+For example by overwriting the `source_paths` method to contain the
+location of your template. Now methods like `copy_file` will accept
+relative paths to your template's location.
+
+```ruby
+def source_paths
+  [File.expand_path(File.dirname(__FILE__))]
+end
+```

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.
@@ -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,9 @@ 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 Rails::Rack::Debugger
 use Rack::ContentLength
 run Rails.application
 ```
@@ -113,12 +111,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 +130,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 +140,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 +181,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
+#### Deleting a Middleware
 
-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.
-
-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,116 +223,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:
 
- **`Rack::Sendfile`**
+**`Rack::Sendfile`**
 
 * Sets server specific X-Sendfile header. Configure this via `config.action_dispatch.x_sendfile_header` option.
 
- **`ActionDispatch::Static`**
+**`ActionDispatch::Static`**
 
 * Used to serve static assets. Disabled if `config.serve_static_assets` 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.
 
- **`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`**
+**`ActionDispatch::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
 ---------