Merge branch 'master' of github.com:rails/docrails

activerecord/lib/active_record/attribute_methods/serialization.rb

@@ -24,6 +24,9 @@ module ActiveRecord
         # serialized object must be of that class on retrieval or
         # <tt>SerializationTypeMismatch</tt> will be raised.
         #
+        # A notable side effect of serialized attributes is that the model will
+        # be updated on every save, even if it is not dirty.
+        #
         # ==== Parameters
         #
         # * +attr_name+ - The field name that should be serialized.

activerecord/lib/active_record/store.rb

@@ -15,6 +15,10 @@ module ActiveRecord
   # You can set custom coder to encode/decode your serialized attributes to/from different formats.
   # JSON, YAML, Marshal are supported out of the box. Generally it can be any wrapper that provides +load+ and +dump+.
   #
+  # NOTE - If you are using special PostgreSQL columns like +hstore+ or +json+ there is no need for
+  # the serialization provieded by +store+. You can simply use +store_accessor+ instead to generate
+  # the accessor methods.
+  #
   # Examples:
   #
   #   class User < ActiveRecord::Base

guides/source/2_3_release_notes.md

@@ -604,7 +604,7 @@ Deprecated
 A few pieces of older code are deprecated in this release:
 
 * If you're one of the (fairly rare) Rails developers who deploys in a fashion that depends on the inspector, reaper, and spawner scripts, you'll need to know that those scripts are no longer included in core Rails. If you need them, you'll be able to pick up copies via the [irs_process_scripts](http://github.com/rails/irs_process_scripts/tree) plugin.
-* `render_component` goes from "deprecated" to "nonexistent" in Rails 2.3. If you still need it, you can install the [render_component plugin](http://github.com/rails/render_component/tree/master.)
+* `render_component` goes from "deprecated" to "nonexistent" in Rails 2.3. If you still need it, you can install the [render_component plugin](http://github.com/rails/render_component/tree/master).
 * Support for Rails components has been removed.
 * If you were one of the people who got used to running `script/performance/request` to look at performance based on integration tests, you need to learn a new trick: that script has been removed from core Rails now. There's a new request_profiler plugin that you can install to get the exact same functionality back.
 * `ActionController::Base#session_enabled?` is deprecated because sessions are lazy-loaded now.

guides/source/3_2_release_notes.md

@@ -375,7 +375,7 @@ Active Record
 
 * Support index sort order in SQLite, MySQL and PostgreSQL adapters.
 
-* Allow the `:class_name` option for associations to take a symbol in addition to a string. This is to avoid confusing newbies, and to be consistent with the fact that other options like :foreign_key already allow a symbol or a string.
+* Allow the `:class_name` option for associations to take a symbol in addition to a string. This is to avoid confusing newbies, and to be consistent with the fact that other options like `:foreign_key` already allow a symbol or a string.
 
     ```ruby
     has_many :clients, :class_name => :Client # Note that the symbol need to be capitalized

guides/source/4_0_release_notes.md

@@ -165,9 +165,9 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/4-0-stable/a
 
 ### Notable changes
 
-* Replace deprecated `memcache-client` gem with `dalli` in ActiveSupport::Cache::MemCacheStore.
+* Replace deprecated `memcache-client` gem with `dalli` in `ActiveSupport::Cache::MemCacheStore`.
 
-* Optimize ActiveSupport::Cache::Entry to reduce memory and processing overhead.
+* Optimize `ActiveSupport::Cache::Entry` to reduce memory and processing overhead.
 
 * Inflections can now be defined per locale. `singularize` and `pluralize` accept locale as an extra argument.
 

guides/source/active_record_callbacks.md

@@ -290,7 +290,7 @@ Here's an example where we create a class with an `after_destroy` callback for a
 ```ruby
 class PictureFileCallbacks
   def after_destroy(picture_file)
-    if File.exists?(picture_file.filepath)
+    if File.exist?(picture_file.filepath)
       File.delete(picture_file.filepath)
     end
   end
@@ -310,7 +310,7 @@ Note that we needed to instantiate a new `PictureFileCallbacks` object, since we
 ```ruby
 class PictureFileCallbacks
   def self.after_destroy(picture_file)
-    if File.exists?(picture_file.filepath)
+    if File.exist?(picture_file.filepath)
       File.delete(picture_file.filepath)
     end
   end

guides/source/engines.md

@@ -875,7 +875,7 @@ end
 
 When Rails looks for a view to render, it will first look in the `app/views` directory of the application. If it cannot find the view there, then it will check in the `app/views` directories of all engines which have this directory.
 
-In the `blorgh` engine, there is a currently a file at `app/views/blorgh/posts/index.html.erb`. When the engine is asked to render the view for `Blorgh::PostsController`'s `index` action, it will first see if it can find it at `app/views/blorgh/posts/index.html.erb` within the application and then if it cannot it will look inside the engine.
+When the application is asked to render the view for `Blorgh::PostsController`'s index action, it will look the path `app/views/blorgh/posts/index.html.erb`, first within the application. If it cannot find it, it will look inside the engine.
 
 You can override this view in the application by simply creating a new file at `app/views/blorgh/posts/index.html.erb`. Then you can completely change what this view would normally output.
 

guides/source/i18n.md

@@ -492,12 +492,14 @@ Overview of the I18n API Features
 
 You should have good understanding of using the i18n library now, knowing all necessary aspects of internationalizing a basic Rails application. In the following chapters, we'll cover it's features in more depth.
 
+These chapters will show examples using both the `I18n.translate` method as well as the [`translate` view helper method](http://api.rubyonrails.org/classes/ActionView/Helpers/TranslationHelper.html#method-i-translate) (noting the additional feature provide by the view helper method).
+
 Covered are features like these:
 
 * looking up translations
 * interpolating data into translations
 * pluralizing translations
-* using safe HTML translations
+* using safe HTML translations (view helper method only)
 * localizing dates, numbers, currency, etc.
 
 ### Looking up Translations
@@ -585,6 +587,8 @@ you can look up the `books.index.title` value **inside** `app/views/books/index.
 <%= t '.title' %>
 ```
 
+NOTE: Automatic translation scoping by partial is only available from the `translate` view helper method.
+
 ### Interpolation
 
 In many cases you want to abstract your translations so that **variables can be interpolated into the translation**. For this reason the I18n API provides an interpolation feature.
@@ -673,6 +677,8 @@ en:
 <div><%= t('title.html') %></div>
 ```
 
+NOTE: Automatic conversion to HTML safe translate text is only available from the `translate` view helper method.
+
 ![i18n demo html safe](images/i18n/demo_html_safe.png)
 
 How to Store your Custom Translations

guides/source/initialization.md

@@ -29,9 +29,42 @@ quickly.
 Launch!
 -------
 
-Let's start to boot and initialize the app. It all begins with your app's
-`bin/rails` executable. A Rails application is usually started by running
-`rails console` or `rails server`.
+Let's start to boot and initialize the app. A Rails application is usually
+started by running `rails console` or `rails server`.
+
+### `railties/bin/rails`
+
+The `rails` in the command `rails server` is a ruby executable in your load
+path. This executable contains the following lines:
+
+```ruby
+version = ">= 0"
+load Gem.bin_path('railties', 'rails', version)
+```
+
+If you try out this command in a Rails console, you would see that this loads
+`railties/bin/rails`. A part of the file `railties/bin/rails.rb` has the
+following code:
+
+```ruby
+require "rails/cli"
+```
+
+The file `railties/lib/rails/cli` in turn calls
+`Rails::AppRailsLoader.exec_app_rails`.
+
+### `railties/lib/rails/app_rails_loader.rb`
+
+The primary goal of the function `exec_app_rails` is to execute your app's
+`bin/rails`. If the current directory does not have a `bin/rails`, it will
+navigate upwards until it finds a `bin/rails` executable. Thus one can invoke a
+`rails` command from anywhere inside a rails application.
+
+For `rails server` the equivalent of the following command is executed:
+
+```bash
+$ exec ruby bin/rails server
+```
 
 ### `bin/rails`
 
@@ -54,7 +87,7 @@ The `APP_PATH` constant will be used later in `rails/commands`. The `config/boot
 # Set up gems listed in the Gemfile.
 ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
 
-require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
 ```
 
 In a standard Rails application, there's a `Gemfile` which declares all
@@ -121,7 +154,7 @@ when 'server'
   # Change to the application's path if there is no config.ru file in current directory.
   # This allows us to run `rails server` from other directories, but still get
   # the main config.ru and properly set the tmp directory.
-  Dir.chdir(File.expand_path('../../', APP_PATH)) unless File.exists?(File.expand_path("config.ru"))
+  Dir.chdir(File.expand_path('../../', APP_PATH)) unless File.exist?(File.expand_path("config.ru"))
 
   require 'rails/commands/server'
   Rails::Server.new.tap do |server|

guides/source/rails_on_rack.md

@@ -83,7 +83,7 @@ To use `rackup` instead of Rails' `rails server`, you can put the following insi
 # Rails.root/config.ru
 require ::File.expand_path('../config/environment', __FILE__)
 
-use Rack::Debugger
+use Rails::Rack::Debugger
 use Rack::ContentLength
 run Rails.application
 ```
@@ -225,95 +225,95 @@ 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::Migration::CheckPending`**
+**`ActiveRecord::Migration::CheckPending`**
 
 * Checks pending migrations and raises `ActiveRecord::PendingMigrationError` if any migrations are pending.
 
- **`ActiveRecord::ConnectionAdapters::ConnectionManagement`**
+**`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.