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

activerecord/lib/active_record/associations.rb

@@ -1329,7 +1329,7 @@ def has_one(name, options = {})
       #
       # [:class_name]
       #   Specify the class name of the association. Use it only if that name can't be inferred
-      #   from the association name. So <tt>has_one :author</tt> will by default be linked to the Author class, but
+      #   from the association name. So <tt>belongs_to :author</tt> will by default be linked to the Author class, but
       #   if the real class name is Person, you'll have to specify it with this option.
       # [:conditions]
       #   Specify the conditions that the associated object must meet in order to be included as a +WHERE+

activerecord/lib/active_record/relation/query_methods.rb

@@ -147,6 +147,42 @@ def from(value)
       relation
     end
 
+    # Used to extend a scope with additional methods, either through
+    # a module or through a block provided. 
+    # 
+    # The object returned is a relation, which can be further extended.
+    #
+    # === Using a module
+    #
+    #   module Pagination
+    #     def page(number)
+    #       # pagination code goes here
+    #     end
+    #   end
+    #
+    #   scope = Model.scoped.extending(Pagination)
+    #   scope.page(params[:page])
+    #
+    # You can also pass a list of modules:
+    #
+    #   scope = Model.scoped.extending(Pagination, SomethingElse)
+    #
+    # === Using a block
+    #
+    #   scope = Model.scoped.extending do
+    #     def page(number)
+    #       # pagination code goes here 
+    #     end
+    #   end
+    #   scope.page(params[:page])
+    #
+    # You can also use a block and a module list:
+    #
+    #   scope = Model.scoped.extending(Pagination) do
+    #     def per_page(number)
+    #       # pagination code goes here 
+    #     end
+    #   end
     def extending(*modules)
       modules << Module.new(&Proc.new) if block_given?
 

railties/guides/source/action_controller_overview.textile

@@ -815,9 +815,3 @@ end
 </ruby>
 
 Please note that if you found yourself adding +force_ssl+ to many controllers, you may found yourself wanting to force the whole application to use HTTPS instead. In that case, you can set the +config.force_ssl+ in your environment file.
-
-h3. Changelog
-
-* February 17, 2009: Yet another proofread by Xavier Noria.
-
-* November 4, 2008: First release version by Tore Darell

railties/guides/source/action_mailer_basics.textile

@@ -521,8 +521,3 @@ end
 </ruby>
 
 In the test we send the email and store the returned object in the +email+ variable. We then ensure that it was sent (the first assert), then, in the second batch of assertions, we ensure that the email does indeed contain what we expect.
-
-h3. Changelog
-
-* September 1, 2011: Changed the lines that said <tt>config/environments/env.rb</tt> to <tt>config/environments/$RAILS_ENV.rb</tt>.  People were mis-interpreting the filename to literally be env.rb.  "Andy Leeper":http://mochaleaf.com
-* September 30, 2010: Fixed typos and reformatted Action Mailer configuration table for better understanding. "Jaime Iniesta":http://jaimeiniesta.com

railties/guides/source/action_view_overview.textile

@@ -1495,10 +1495,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.
-
-h3. Changelog
-
-* May 29, 2011: Removed references to remote_* helpers - Vijay Dev
-* April 16, 2011: Added 'Using Action View with Rails', 'Templates' and 'Partials' sections. "Sebastian Martinez":http://wyeworks.com
-* September 3, 2009: Continuing work by Trevor Turk, leveraging the Action Pack docs and "What's new in Edge Rails":http://ryandaigle.com/articles/2007/8/3/what-s-new-in-edge-rails-partials-get-layouts
-* April 5, 2009: Starting work by Trevor Turk, leveraging Mike Gunderloy's docs

railties/guides/source/active_model_basics.textile

@@ -203,8 +203,3 @@ person.valid?                        #=> true
 person.token = nil
 person.valid?                        #=> raises ActiveModel::StrictValidationFailed
 </ruby>
-
-h3. Changelog
-
-* August 24, 2011: Add strict validation usage example. "Bogdan Gusiev":http://gusiev.com
-* August 5, 2011: Initial version by "Arun Agrawal":http://github.com/arunagw

railties/guides/source/active_record_querying.textile

@@ -1042,20 +1042,26 @@ INSERT INTO clients (created_at, first_name, locked, orders_count, updated_at) V
 COMMIT
 </sql>
 
-+first_or_create+ returns either the record that already existed or the new record. In our case, we didn't already have a client named Andy so the record was created an returned.
++first_or_create+ returns either the record that already exists or the new record. In our case, we didn't already have a client named Andy so the record is created and returned.
 
 The new record might not be saved to the database; that depends on whether validations passed or not (just like +create+).
 
 It's also worth noting that +first_or_create+ takes into account the arguments of the +where+ method. In the example above we didn't explicitly pass a +:first_name => 'Andy'+ argument to +first_or_create+. However, that was used when creating the new record because it was already passed before to the +where+ method.
 
-NOTE: On previous versions of Rails you could do a similar thing with the +find_or_create_by+ method. Following our example, you could also run something like +Client.find_or_create_by_first_name(:first_name => "Andy", :locked => false)+. This method still works, but it's encouraged to use +first_or_create+ because it's more explicit on what arguments are used to _find_ the record and what arguments are used to _create_ it, resulting in less confusion overall.
+You can do the same with the +find_or_create_by+ method:
+
+<ruby>
+Client.find_or_create_by_first_name(:first_name => "Andy", :locked => false)
+</ruby>
+
+This method still works, but it's encouraged to use +first_or_create+ because it's more explicit on which arguments are used to _find_ the record and which are used to _create_, resulting in less confusion overall.
 
 h4. +first_or_create!+
 
 You can also use +first_or_create!+ to raise an exception if the new record is invalid. Validations are not covered on this guide, but let's assume for a moment that you temporarily add
 
 <ruby>
-    validates :orders_count, :presence => true
+validates :orders_count, :presence => true
 </ruby>
 
 to your +Client+ model. If you try to create a new +Client+ without passing an +orders_count+, the record will be invalid and an exception will be raised:
@@ -1065,14 +1071,12 @@ Client.where(:first_name => 'Andy').first_or_create!(:locked => false)
 # => ActiveRecord::RecordInvalid: Validation failed: Orders count can't be blank
 </ruby>
 
-NOTE: Be sure to check the extensive *Active Record Validations and Callbacks Guide* for more information about validations.
+h4. +first_or_initialize+
 
-h4. +first_or_new+
-
-The +first_or_new+ method will work just like +first_or_create+ but it will not call +create+ but +new+. This means that a new model instance will be created in memory but won't be saved to the database. Continuing with the +first_or_create+ example, we now want the client named 'Nick':
+The +first_or_initialize+ method will work just like +first_or_create+ but it will not call +create+ but +new+. This means that a new model instance will be created in memory but won't be saved to the database. Continuing with the +first_or_create+ example, we now want the client named 'Nick':
 
 <ruby>
-nick = Client.where(:first_name => 'Nick').first_or_new(:locked => false)
+nick = Client.where(:first_name => 'Nick').first_or_initialize(:locked => false)
 # => <Client id: nil, first_name: "Nick", orders_count: 0, locked: false, created_at: "2011-08-30 06:09:27", updated_at: "2011-08-30 06:09:27">
 
 nick.persisted?
@@ -1095,8 +1099,6 @@ nick.save
 # => true
 </ruby>
 
-Just like you can use *+build+* instead of *+new+*, you can use *+first_or_build+* instead of *+first_or_new+*.
-
 h3. Finding by SQL
 
 If you'd like to use your own SQL to find records in a table you can use +find_by_sql+. The +find_by_sql+ method will return an array of objects even if the underlying query returns just a single record. For example you could run this query:
@@ -1246,12 +1248,3 @@ Client.sum("orders_count")
 </ruby>
 
 For options, please see the parent section, "Calculations":#calculations.
-
-h3. Changelog
-
-* June 26 2011: Added documentation for the +scoped+, +unscoped+ and +default+ methods. "Ryan Bigg":credits.html#radar
-* December 23 2010: Add documentation for the +scope+ method. "Ryan Bigg":credits.html#radar
-* April 7, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
-* February 3, 2010: Update to Rails 3 by "James Miller":credits.html#bensie
-* February 7, 2009: Second version by "Pratik":credits.html#lifo
-* December 29 2008: Initial version by "Ryan Bigg":credits.html#radar

railties/guides/source/active_record_validations_callbacks.textile

@@ -1267,14 +1267,3 @@ end
 </ruby>
 
 The +after_commit+ and +after_rollback+ callbacks are guaranteed to be called for all models created, updated, or destroyed within a transaction block. If any exceptions are raised within one of these callbacks, they will be ignored so that they don't interfere with the other callbacks. As such, if your callback code could raise an exception, you'll need to rescue it and handle it appropriately within the callback.
-
-h3. Changelog
-
-* February 17, 2011: Add description of transaction callbacks.
-* July 20, 2010: Fixed typos and rephrased some paragraphs for clarity. "Jaime Iniesta":http://jaimeiniesta.com
-* May 24, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
-* May 15, 2010: Validation Errors section updated by "Emili Parreño":http://www.eparreno.com
-* March 7, 2009: Callbacks revision by Trevor Turk
-* February 10, 2009: Observers revision by Trevor Turk
-* February 5, 2009: Initial revision by Trevor Turk
-* January 9, 2009: Initial version by "Cássio Marques":credits.html#cmarques

railties/guides/source/active_resource_basics.textile

@@ -118,7 +118,3 @@ This validates the resource with any local validations written in base class and
 h5. valid?
 
 Runs all the local validations and will return true if no errors.
-
-h3. Changelog
-
-* July 30, 2011: Initial version by "Vishnu Atrai":http://github.com/vatrai

railties/guides/source/active_support_core_extensions.textile

@@ -3599,8 +3599,3 @@ end
 </ruby>
 
 NOTE: Defined in +active_support/core_ext/load_error.rb+.
-
-h3. Changelog
-
-* August 10, 2010: Starts to take shape, added to the index.
-* April 18, 2009: Initial version by "Xavier Noria":credits.html#fxn

railties/guides/source/api_documentation_guidelines.textile

@@ -183,7 +183,3 @@ self.class_eval %{
   end
 }
 </ruby>
-
-h3. Changelog
-
-* July 17, 2010: ported from the docrails wiki and revised by "Xavier Noria":credits.html#fxn

railties/guides/source/asset_pipeline.textile

@@ -63,7 +63,7 @@ This has several disadvantages:
 <ol>
   <li>
     <strong>Not all caches will cache content with a query string</strong><br>
-    "Steve Souders recommends":http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/, "...avoiding a querystring for cacheable resources". He found that in these case 5-20% of requests will not be cached.
+    "Steve Souders recommends":http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/, "...avoiding a querystring for cacheable resources". He found that in this case 5-20% of requests will not be cached.
   </li>
   <li>
     <strong>The file name can change between nodes in multi-server environments.</strong><br>
@@ -132,7 +132,7 @@ In regular views you can access images in the +assets/images+ directory like thi
 
 Provided that the pipeline is enabled within your application (and not disabled in the current environment context), this file is served by Sprockets. If a file exists at +public/assets/rails.png+ it is served by the webserver.
 
-Alternatively, a request for a file with an MD5 hash such as +public/assets/rails-af27b6a414e6da00003503148be9b409.png+ is treated the same way. How these hashes are generated is covered in the "Production Assets":#production_assets section later on in this guide.
+Alternatively, a request for a file with an MD5 hash such as +public/assets/rails-af27b6a414e6da00003503148be9b409.png+ is treated the same way. How these hashes are generated is covered in the "In Production":#in-production section later on in this guide.
 
 Sprockets will also look through the paths specified in +config.assets.paths+ which includes the standard application paths and any path added by Rails engines.
 
@@ -403,7 +403,21 @@ For Apache:
 </LocationMatch>
 </plain>
 
-TODO: nginx instructions
+For nginx:
+
+<plain>
+location ~ ^/assets/ {
+  expires 1y;
+  add_header Cache-Control public;
+
+  # Some browsers still send conditional-GET requests if there's a
+  # Last-Modified header or an ETag header even if they haven't
+  # reached the expiry date sent in the Expires header.
+  add_header Last-Modified "";
+  add_header ETag "";
+  break;
+}
+</plain>
 
 When files are precompiled, Sprockets also creates a "Gzip":http://en.wikipedia.org/wiki/Gzip (.gz) version of your assets. This avoids the server having to do this for any requests; it can simply read the compressed files from disk. You must configure your server to use gzip compression and serve the compressed assets that will be stored in the +public/assets+ folder. The following configuration options can be used:
 
@@ -537,7 +551,7 @@ WARNING: If you are upgrading an existing application and intend to use this opt
 
 h3. How Caching Works
 
-Sprockets uses the default rails cache store to cache assets in development and production.
+Sprockets uses the default Rails cache store to cache assets in development and production.
 
 TODO: Add more about changing the default store.
 

railties/guides/source/association_basics.textile

@@ -1855,17 +1855,8 @@ class Customer < ActiveRecord::Base
 end
 </ruby>
 
-Extensions can refer to the internals of the association proxy using these three accessors:
+Extensions can refer to the internals of the association proxy using these three attributes of the +proxy_association+ accessor:
 
-* +proxy_owner+ returns the object that the association is a part of.
-* +proxy_reflection+ returns the reflection object that describes the association.
-* +proxy_target+ returns the associated object for +belongs_to+ or +has_one+, or the collection of associated objects for +has_many+ or +has_and_belongs_to_many+.
-
-h3. Changelog
-
-* April 7, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
-* April 19, 2009: Added +:touch+ option to +belongs_to+ associations by "Mike Gunderloy":credits.html#mgunderloy
-* February 1, 2009: Added +:autosave+ option "Mike Gunderloy":credits.html#mgunderloy
-* September 28, 2008: Corrected +has_many :through+ diagram, added polymorphic diagram, some reorganization by "Mike Gunderloy":credits.html#mgunderloy . First release version.
-* September 22, 2008: Added diagrams, misc. cleanup by "Mike Gunderloy":credits.html#mgunderloy (not yet approved for publication)
-* September 14, 2008: initial version by "Mike Gunderloy":credits.html#mgunderloy (not yet approved for publication)
+* +proxy_association.owner+ returns the object that the association is a part of.
+* +proxy_association.reflection+ returns the reflection object that describes the association.
+* +proxy_association.target+ returns the associated object for +belongs_to+ or +has_one+, or the collection of associated objects for +has_many+ or +has_and_belongs_to_many+.

railties/guides/source/caching_with_rails.textile

@@ -403,14 +403,3 @@ end
 h3. Further reading
 
 * "Scaling Rails Screencasts":http://railslab.newrelic.com/scaling-rails
-
-h3. Changelog
-
-* Feb       17, 2011: Document 3.0.0 changes to ActiveSupport::Cache
-* May       02, 2009: Formatting cleanups
-* April     26, 2009: Clean up typos in submitted patch
-* April      1, 2009: Made a bunch of small fixes
-* February  22, 2009: Beefed up the section on cache_stores
-* December  27, 2008: Typo fixes
-* November  23, 2008: Incremental updates with various suggested changes and formatting cleanup
-* September 15, 2008: Initial version by Aditya Chadha

railties/guides/source/configuring.textile

@@ -604,11 +604,3 @@ The error occurred while evaluating nil.each
 *+set_routes_reloader+* Configures Action Dispatch to reload the routes file using +ActionDispatch::Callbacks.to_prepare+.
 
 *+disable_dependency_loading+* Disables the automatic dependency loading if the +config.cache_classes+ is set to true and +config.dependency_loading+ is set to false.
-
-h3. Changelog
-
-* December 3, 2010: Added initialization events for Rails 3 ("Ryan Bigg":http://ryanbigg.com)
-* November 26, 2010: Removed all config settings not available in Rails 3 ("Ryan Bigg":http://ryanbigg.com)
-* August 13, 2009: Updated with config syntax and added general configuration options by "John Pignata"
-* January 3, 2009: First reasonably complete draft by "Mike Gunderloy":credits.html#mgunderloy
-* November 5, 2008: Rough outline by "Mike Gunderloy":credits.html#mgunderloy

railties/guides/source/contributing_to_ruby_on_rails.textile

@@ -200,11 +200,11 @@ You can also invoke +test_jdbcmysql+, +test_jdbcsqlite3+ or +test_jdbcpostgresql
 
 h4. Older versions of Ruby on Rails
 
-If you want to add a fix to older versions of Ruby on Rails, you'll need to set up and switch to your own local tracking branch. Here is an example to switch to the 2-3-stable branch:
+If you want to add a fix to older versions of Ruby on Rails, you'll need to set up and switch to your own local tracking branch. Here is an example to switch to the 3-0-stable branch:
 
 <shell>
-$ git branch --track 2-3-stable origin/2-3-stable
-$ git checkout 2-3-stable
+$ git branch --track 3-0-stable origin/3-0-stable
+$ git checkout 3-0-stable
 </shell>
 
 TIP: You may want to "put your git branch name in your shell prompt":http://qugstart.com/blog/git-and-svn/add-colored-git-branch-name-to-your-shell-prompt/ to make it easier to remember which version of the code you're working with.
@@ -383,13 +383,3 @@ And then...think about your next contribution!
 h3. Rails Contributors
 
 All contributions, either via master or docrails, get credit in "Rails Contributors":http://contributors.rubyonrails.org.
-
-h3. Changelog
-
-* May 12, 2011: Modified to prefer topic branches instead of master branch for users contributions by "Guillermo Iguaran":http://quillarb.org
-* April 29, 2011: Reflect GitHub Issues and Pull Request workflow by "Dan Pickett":http://www.enlightsolutions.com
-* April 14, 2011: Modified Contributing to the Rails Code section to add '[#ticket_number state:commited]' on patches commit messages by "Sebastian Martinez":http://wyeworks.com
-* December 28, 2010: Complete revision by "Xavier Noria":credits.html#fxn
-* April 6, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
-* August 1, 2009: Updates/amplifications by "Mike Gunderloy":credits.html#mgunderloy
-* March 2, 2009: Initial draft by "Mike Gunderloy":credits.html#mgunderloy

railties/guides/source/debugging_rails_applications.textile

@@ -712,10 +712,3 @@ h3. References
 * "ruby-debug cheat sheet":http://cheat.errtheblog.com/s/rdebug/
 * "Ruby on Rails Wiki: How to Configure Logging":http://wiki.rubyonrails.org/rails/pages/HowtoConfigureLogging
 * "Bleak House Documentation":http://blog.evanweaver.com/files/doc/fauna/bleak_house/files/README.html
-
-h3. Changelog
-
-* April 4, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
-* November 3, 2008: Accepted for publication. Added RJS, memory leaks and plugins chapters by "Emilio Tagua":credits.html#miloops
-* October 19, 2008: Copy editing pass by "Mike Gunderloy":credits.html#mgunderloy
-* September 16, 2008: initial version by "Emilio Tagua":credits.html#miloops

railties/guides/source/form_helpers.textile

@@ -796,13 +796,3 @@ Many apps grow beyond simple forms editing a single object. For example when cre
 * Eloy Duran's "complex-forms-examples":https://github.com/alloy/complex-form-examples/ application
 * Lance Ivy's "nested_assignment":https://github.com/cainlevy/nested_assignment/tree/master plugin and "sample application":https://github.com/cainlevy/complex-form-examples/tree/cainlevy
 * James Golick's "attribute_fu":https://github.com/jamesgolick/attribute_fu plugin
-
-h3. Changelog
-
-* February 5, 2011: Added 'Forms to external resources' section. Timothy N. Tsvetkov <timothy.tsvetkov@gmail.com>
-* April 6, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
-
-h3. Authors
-
-* Mislav Marohnić <mislav.marohnic@gmail.com>
-* "Frederick Cheung":credits.html#fcheung