railties 3.1.0.beta1 → 3.1.0.rc1

data/CHANGELOG

@@ -1,5 +1,19 @@
 *Rails 3.1.0 (unreleased)*
 
+* Application and plugin generation run bundle install unless --skip-gemfile or --skip-bundle. [fxn]
+
+* Fixed database tasks for jdbc* adapters #jruby
+
+  [Rashmi Yadav]
+
+* Template generation for jdbcpostgresql  #jruby
+
+  [Vishnu Atrai]
+
+* Template generation for jdbcmysql and jdbcsqlite3 #jruby
+
+  [Arun Agrawal]
+
 * The -j option of the application generator accepts an arbitrary string. If passed "foo",
 the gem "foo-rails" is added to the Gemfile, and the application JavaScript manifest
 requires "foo" and "foo_ujs". As of this writing "prototype-rails" and "jquery-rails"
@@ -16,7 +30,7 @@ by the prototype-rails gem. [fxn]
 
 * jQuery is the new default JavaScript library. [fxn]
 
-* Changed scaffold and app generator to create Ruby 1.9 style hash when running on Ruby 1.9 [Prem Sichanugrist]
+* Changed scaffold, application, and mailer generator to create Ruby 1.9 style hash when running on Ruby 1.9 [Prem Sichanugrist]
 
   So instead of creating something like:
 
@@ -62,10 +76,42 @@ by the prototype-rails gem. [fxn]
 
 * Include all helpers from plugins and shared engines in application [Piotr Sarnacki]
 
+
+*Rails 3.0.7 (April 18, 2011)*
+
+*No changes.
+
+
+*Rails 3.0.6 (April 5, 2011)
+
+* No changes.
+
+
+*Rails 3.0.5 (February 26, 2011)*
+
+* No changes.
+
+
+*Rails 3.0.4 (February 8, 2011)*
+
+* No changes.
+
+
+*Rails 3.0.3 (November 16, 2010)*
+
+* No changes.
+
+
+*Rails 3.0.2 (November 15, 2010)*
+
+* No changes.
+
+
 *Rails 3.0.1 (October 15, 2010)*
 
 * No Changes, just a version bump.
 
+
 *Rails 3.0.0 (August 29, 2010)*
 
 * Application generation: --skip-testunit and --skip-activerecord become --skip-test-unit and --skip-active-record respectively. [fxn]

data/guides/rails_guides/generator.rb

@@ -38,9 +38,10 @@
 #     Note that if you are working on a guide generation will by default process
 #     only that one, so ONLY is rarely used nowadays.
 #
-#   LANGUAGE
-#     Use LANGUAGE when you want to generate translated guides in <tt>source/<LANGUAGE></tt>
-#     folder (such as <tt>source/es</tt>). Ignore it when generating English guides.
+#   GUIDES_LANGUAGE
+#     Use GUIDES_LANGUAGE when you want to generate translated guides in
+#     <tt>source/<GUIDES_LANGUAGE></tt> folder (such as <tt>source/es</tt>).
+#     Ignore it when generating English guides.
 #
 #   EDGE
 #     Set to "1" to indicate generated guides should be marked as edge. This
@@ -67,7 +68,7 @@ module RailsGuides
     GUIDES_RE = /\.(?:textile|html\.erb)$/
 
     def initialize(output=nil)
-      @lang = ENV['LANGUAGE']
+      @lang = ENV['GUIDES_LANGUAGE']
       initialize_dirs(output)
       create_output_dir_if_needed
       set_flags_from_environment

data/guides/source/action_controller_overview.textile

@@ -110,6 +110,32 @@ When this form is submitted, the value of +params[:client]+ will be <tt>{"name"
 
 Note that the +params+ hash is actually an instance of +HashWithIndifferentAccess+ from Active Support, which acts like a hash that lets you use symbols and strings interchangeably as keys.
 
+h4. JSON/XML parameters
+
+If you're writing a web service application, you might find yourself more comfortable on accepting parameters in JSON or XML format. Rails will automatically convert your parameters into +params+ hash, which you'll be able to access like you would normally do with form data.
+
+So for example, if you are sending this JSON parameter:
+
+<pre>
+{ "company": { "name": "acme", "address": "123 Carrot Street" } }
+</pre>
+
+You'll get <tt>params[:company]</tt> as <tt>{ :name => "acme", "address" => "123 Carrot Street" }</tt>.
+
+Also, if you've turned on +config.wrap_parameters+ in your initializer or calling +wrap_parameters+ in your controller, you can safely omit the root element in the JSON/XML parameter. The parameters will be cloned and wrapped in the key according to your controller's name by default. So the above parameter can be written as:
+
+<pre>
+{ "name": "acme", "address": "123 Carrot Street" }
+</pre>
+
+And assume that you're sending the data to +CompaniesController+, it would then be wrapped in +:company+ key like this:
+
+<ruby>
+{ :name => "acme", :address => "123 Carrot Street", :company => { :name => "acme", :address => "123 Carrot Street" }}
+</ruby>
+
+You can customize the name of the key or specific parameters you want to wrap by consulting the "API documentation":http://api.rubyonrails.org/classes/ActionController/ParamsWrapper.html
+
 h4. Routing Parameters
 
 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:

data/guides/source/active_support_core_extensions.textile

@@ -417,6 +417,14 @@ silence_stream(STDOUT) do
 end
 </ruby>
 
+The +quietly+ method addresses the common use case where you want to silence STDOUT and STDERR, even in subprocesses:
+
+<ruby>
+quietly { system 'bundle install' }
+</ruby>
+
+For example, the railties test suite uses that one in a few places to prevent command messages from being echoed intermixed with the progress status.
+
 Silencing exceptions is also possible with +suppress+. This method receives an arbitrary number of exception classes. If an exception is raised during the execution of the block and is +kind_of?+ any of the arguments, +suppress+ captures it and returns silently. Otherwise the exception is reraised:
 
 <ruby>
@@ -1833,6 +1841,8 @@ The method +ordinalize+ returns the ordinal string corresponding to the receiver
 2.ordinalize    # => "2nd"
 53.ordinalize   # => "53rd"
 2009.ordinalize # => "2009th"
+-21.ordinalize  # => "-21st"
+-134.ordinalize # => "-134th"
 </ruby>
 
 NOTE: Defined in +active_support/core_ext/integer/inflections.rb+.

data/guides/source/association_basics.textile

@@ -342,9 +342,9 @@ In designing a data model, you will sometimes find a model that should have a re
 
 <ruby>
 class Employee < ActiveRecord::Base
-  has_many :subordinates, :class_name => "Employee",
+  has_many :subordinates, :class_name => "Employee"
+  belongs_to :manager, :class_name => "Employee",
     :foreign_key => "manager_id"
-  belongs_to :manager, :class_name => "Employee"
 end
 </ruby>
 

data/guides/source/caching_with_rails.textile

@@ -98,7 +98,7 @@ You can also use +:if+ (or +:unless+) to pass a Proc that specifies when the act
 
 You can modify the default action cache path by passing a +:cache_path+ option. This will be passed directly to +ActionCachePath.path_for+. This is handy for actions with multiple possible routes that should be cached differently. If a block is given, it is called with the current controller instance.
 
-Finally, if you are using memcached, you can also pass +:expires_in+. In fact, all parameters not used by +caches_action+ are sent to the underlying cache store.
+Finally, if you are using memcached or Ehcache, you can also pass +:expires_in+. In fact, all parameters not used by +caches_action+ are sent to the underlying cache store.
 
 INFO: Action caching runs in an after filter. Thus, invalid requests won't generate spurious cache entries as long as you halt them. Typically, a redirection in some before filter that checks request preconditions does the job.
 
@@ -304,6 +304,35 @@ The +write+ and +fetch+ methods on this cache accept two additional options that
 ActionController::Base.cache_store = :mem_cache_store, "cache-1.example.com", "cache-2.example.com"
 </ruby>
 
+h4. ActiveSupport::Cache::EhcacheStore
+
+If you are using JRuby you can use Terracotta's Ehcache as the cache store for your application. Ehcache is an open source Java cache that also offers an enterprise version with increased scalability, management, and commercial support. You must first install the jruby-ehcache-rails3 gem (version 1.1.0 or later) to use this cache store.
+
+<ruby>
+ActionController::Base.cache_store = :ehcache_store
+</ruby>
+
+When initializing the cache, you may use the +:ehcache_config+ option to specify the Ehcache config file to use (where the default is "ehcache.xml" in your Rails config directory), and the :cache_name option to provide a custom name for your cache (the default is rails_cache).
+
+In addition to the standard +:expires_in+ option, the +write+ method on this cache can also accept the additional  +:unless_exist+ option, which will cause the cache store to use Ehcache's +putIfAbsent+ method instead of +put+, and therefore will not overwrite an existing entry. Additionally, the +write+ method supports all of the properties exposed by the "Ehcache Element class":http://ehcache.org/apidocs/net/sf/ehcache/Element.html , including:
+
+|_. Property |_. Argument Type |_. Description |
+| elementEvictionData | ElementEvictionData | Sets this element's eviction data instance. |
+| eternal | boolean | Sets whether the element is eternal. |
+| timeToIdle, tti | int | Sets time to idle |
+| timeToLive, ttl, expires_in | int | Sets time to Live |
+| version | long | Sets the version attribute of the ElementAttributes object. |
+
+These options are passed to the +write+ method as Hash options using either camelCase or underscore notation, as in the following examples:
+
+<ruby>
+Rails.cache.write('key', 'value', :time_to_idle => 60.seconds, :timeToLive => 600.seconds)
+caches_action :index, :expires_in => 60.seconds, :unless_exist => true
+</ruby>
+
+For more information about Ehcache, see "http://ehcache.org/":http://ehcache.org/ .
+For more information about Ehcache for JRuby and Rails, see "http://ehcache.org/documentation/jruby.html":http://ehcache.org/documentation/jruby.html
+
 h4. Custom Cache Stores
 
 You can create your own custom cache store by simply extending +ActiveSupport::Cache::Store+ and implementing the appropriate methods. In this way, you can swap in any number of caching technologies into your Rails application.

data/guides/source/configuring.textile

@@ -9,37 +9,38 @@ endprologue.
 
 h3. Locations for Initialization Code
 
-Rails offers (at least) four good spots to place initialization code:
+Rails offers four standard spots to place initialization code:
 
-* application.rb
-* Environment-specific Configuration Files
+* +config/application.rb+
+* Environment-specific configuration files
 * Initializers
-* After-Initializers
+* After-initializers
 
 h3. Running Code Before Rails
 
-To run some code before Rails itself is loaded, simply put it above the call to
-+require 'rails/all'+ in your +application.rb+.
+In the rare event that your application needs to run some code before Rails itself is loaded, put it above the call to +require 'rails/all'+ in your +config/application.rb+.
 
 h3. Configuring Rails Components
 
-In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The +application.rb+ and environment-specific configuration files (such as +config/environments/production.rb+) allow you to specify the various settings that you want to pass down to all of the components. For example, the default Rails 3.0 +application.rb+ file includes this setting:
+In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The configuration file +config/application.rb+ and environment-specific configuration files (such as +config/environments/production.rb+) allow you to specify the various settings that you want to pass down to all of the components.
+
+For example, the default +config/application.rb+ file includes this setting:
 
 <ruby>
-  config.filter_parameters += [:password]
+config.filter_parameters += [:password]
 </ruby>
 
-This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same +config+ object:
+This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same +config+ object in +config/application.rb+:
 
 <ruby>
-  config.active_record.timestamped_migrations = false
+config.active_record.observers = [:hotel_observer, :review_observer]
 </ruby>
 
 Rails will use that particular setting to configure Active Record.
 
 h4. Rails General Configuration
 
-* +config.after_initialize+ takes a block which will be ran _after_ Rails has finished initializing. Useful for configuring values set up by other initializers:
+* +config.after_initialize+ takes a block which will be ran _after_ Rails has finished initializing the application. That includes the initialization of the framework itself, plugins, engines, and all the application's initializers in +config/initializers+. Useful for configuring values set up by other initializers:
 
 <ruby>
 config.after_initialize do
@@ -47,71 +48,63 @@ config.after_initialize do
 end
 </ruby>
 
-* +config.allow_concurrency+ should be set to +true+ to allow concurrent (threadsafe) action processing. Set to +false+ by default. You probably don't want to call this one directly, though, because a series of other adjustments need to be made for threadsafe mode to work properly. Can also be enabled with +threadsafe!+.
+* +config.allow_concurrency+ should be true to allow concurrent (threadsafe) action processing. False by default. You probably don't want to call this one directly, though, because a series of other adjustments need to be made for threadsafe mode to work properly. Can also be enabled with +threadsafe!+.
 
-* +config.asset_host+ sets the host for the assets. Useful when CDNs are used for hosting assets rather than the application server itself. Shorter version of +config.action_controller.asset_host+.
+* +config.asset_host+ sets the host for the assets. Useful when CDNs are used for hosting assets, or when you want to work around the concurrency constraints builtin in browsers using different domain aliases. Shorter version of +config.action_controller.asset_host+.
 
-* +config.asset_path+ takes a block which configures where assets can be found. Shorter version of +config.action_controller.asset_path+.
+* +config.asset_path+ can take a callable, a string, or be +nil+. Default is +nil+. If set, this configuration parameter let's you decorate asset paths. For example, the normal path for +blog.js+ would be +/javascripts/blog.js+, let that absolute path be +path+. If +config.asset_path+ is a callable, Rails calls it when generating asset paths passing +path+ as argument. If +config.asset_path+ is a string, it is expected to be a +sprintf+ format string with a +%s+ where +path+ will get inserted. In either case, Rails outputs the decorated path. *This option is ignored if the asset pipeline is enabled, which is by default*. Shorter version of +config.action_controller.asset_path+.
 
 <ruby>
-  config.asset_path = proc { |asset_path| "assets/#{asset_path}" }
+config.asset_path = proc { |path| "/blog/public#{path}" }
 </ruby>
 
-* +config.autoload_once_paths+ accepts an array of paths from which Rails will automatically load from only once. All elements of this array must also be in +autoload_paths+.
-
-* +config.autoload_paths+ accepts an array of additional paths to prepend to the load path. By default, all app, lib, vendor and mock paths are included in this list.
+* +config.autoload_once_paths+ accepts an array of paths from which Rails will autoload constants that won't be wiped per request. Relevant if +config.cache_classes+ is false, which is the case in development mode by default. Otherwise, all autoloading happens only once. All elements of this array must also be in +autoload_paths+. Default is an empty array.
 
-* +config.cache_classes+ controls whether or not application classes should be reloaded on each request. Defaults to _true_ in development, _false_ in test and production. Can also be enabled with +threadsafe!+.
+* +config.autoload_paths+ accepts an array of paths from which Rails will autoload constants. Default is all directories under +app+.
 
-* +config.action_view.cache_template_loading+ controls whether or not templates should be reloaded on each request. Defaults to whatever is set for config.cache_classes.
+* +config.cache_classes+ controls whether or not application classes and modules should be reloaded on each request. Defaults to true in development mode, and false in test and production modes. Can also be enabled with +threadsafe!+.
 
-* +config.cache_store+ configures which cache store to use for Rails caching. Options include +:memory_store+, +:file_store+, +:mem_cache_store+ or the name of your own custom class. Defaults to +:file_store+.
+* +config.action_view.cache_template_loading+ controls whether or not templates should be reloaded on each request. Defaults to whatever is set for +config.cache_classes+.
 
-* +config.colorize_logging+ specifies whether or not to use ANSI color codes when logging information. Defaults to _true_.
+* +config.cache_store+ configures which cache store to use for Rails caching. Options include one of the symbols +:memory_store+, +:file_store+, +:mem_cache_store+, or an object that implements the cache API. Defaults to +:file_store+ if the directory +tmp/cache+ exists, and to +:memory_store+ otherwise.
 
-* +config.consider_all_requests_local+ is generally set to +true+ during development and +false+ during production; if it is set to +true+, then any error will cause detailed debugging information to be dumped in the HTTP response. For finer-grained control, set this to +false+ and implement +local_request?+  in controllers to specify which requests should provide debugging information on errors.
+* +config.colorize_logging+ specifies whether or not to use ANSI color codes when logging information. Defaults to true.
 
-* +config.controller_paths+ configures where Rails can find controllers for this application.
+* +config.consider_all_requests_local+ is a flag. If true then any error will cause detailed debugging information to be dumped in the HTTP response, and the +Rails::Info+ controller will show the application runtime context in +/rails/info/properties+. True by default in development and test environments, and false in production mode. For finer-grained control, set this to false and implement +local_request?+ in controllers to specify which requests should provide debugging information on errors.
 
-* +config.dependency_loading+ enables or disables dependency loading during the request cycle. Setting dependency_loading to _true_ will allow new classes to be loaded during a request and setting it to _false_ will disable this behavior. Can also be enabled with +threadsafe!+.
+* +config.dependency_loading+ is a flag that allows you to disable constant autoloading setting it to false. It only has effect if +config.cache_classes+ is true, which it is by default in production mode. This flag is set to false by +config.threadsafe!+.
 
-* +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. Defaults to every folder in the +app+ directory of the application. All elements of this array must also be in +load_paths+.
+* +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. Defaults to every folder in the +app+ directory of the application.
 
 * +config.encoding+ sets up the application-wide encoding. Defaults to UTF-8.
 
 * +config.filter_parameters+ used for filtering out the parameters that you don't want shown in the logs, such as passwords or credit card numbers.
 
-* +config.force_ssl+ forcing all requests to be under HTTPS protocol by using +Rack::SSL+ middleware. This will secure your application from a session hijack attempt.
-
-* +config.helper_paths+ configures where Rails can find helpers for this application.
+* +config.force_ssl+ forces all requests to be under HTTPS protocol by using +Rack::SSL+ middleware.
 
-* +config.log_level+ defines the verbosity of the Rails logger. In production mode, this defaults to +:info+. In development mode, it defaults to +:debug+.
+* +config.log_level+ defines the verbosity of the Rails logger. This option defaults to +:debug+ for all modes except production, where it defaults to +:info+.
 
-* +config.log_path+ overrides the path to the log file to use. Defaults to +log/#{environment}.log+ (e.g. log/development.log or log/production.log).
+* +config.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ +Logger+ class. Defaults to an instance of +ActiveSupport::BufferedLogger+, with auto flushing off in production mode.
 
-* +config.logger+ accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then used to log information from Action Controller. Set to nil to disable logging.
+* +config.middleware+ allows you to configure the application's middleware. This is covered in depth in the "Configuring Middleware":configuring-middleware section below.
 
-* +config.middleware+ allows you to configure the application's middleware. This is covered in depth in the "Configuring Middleware" section below.
+* +config.plugins+ accepts the list of plugins to load. If this is set to +nil+, default, all plugins will be loaded. If this is set to +[]+, no plugins will be loaded. Otherwise, plugins will be loaded in the order specified. This option let's you enforce some particular loading order, useful when dependencies between plugins require it. For that use case, put first the plugins you want to be loaded in a certain order, and then the special symbol +:all+ to have the rest loaded without the need to specify them.
 
-* +config.plugins+ accepts the list of plugins to load. If this is set to nil, all plugins will be loaded. If this is set to [], no plugins will be loaded. Otherwise, plugins will be loaded in the order specified.
+* +config.preload_frameworks+ enables or disables preloading all frameworks at startup. Enabled by +config.threadsafe!+. Defaults to +nil+, so is disabled.
 
-* +config.preload_frameworks+ enables or disables preloading all frameworks at startup. Can also be enabled with +threadsafe!+. Defaults to +nil+, so is disabled.
+* +config.reload_plugins+ enables or disables plugin reloading. Defaults to false.
 
-* +config.reload_plugins+ enables or disables plugin reloading.
+* +config.secret_token+ used for specifying a key which allows sessions for the application to be verified against a known secure key to prevent tampering. Applications get +config.secret_token+ initialized to a random key in +config/initializers/secret_token.rb+.
 
-* +config.root+ configures the root path of the application.
+* +config.serve_static_assets+ configures Rails to serve static assets. Defaults to true, but in the production environment is turned off. The server software used to run the application should be used to serve the assets instead.
 
-* +config.secret_token+ used for specifying a key which allows sessions for the application to be verified against a known secure key to prevent tampering.
-
-* +config.serve_static_assets+ configures Rails to serve static assets. Defaults to _true_, but in the production environment is turned off. The server software used to run the application should be used to serve the assets instead.
-
-* +config.session_store+ is usually set up in +config/initializers/session_store.rb+ and specifies what class to use to store the session. Custom session stores can be specified like so:
+* +config.session_store+ is usually set up in +config/initializers/session_store.rb+ and specifies what class to use to store the session. Possible values are +:cookie_store+, default, +:mem_cache_store+, and +:disabled+. The last one tells Rails not to deal with sessions. Custom session stores can also be specified like so:
 
 <ruby>
-  config.session_store = :my_custom_store
+config.session_store :my_custom_store
 </ruby>
 
-This custom store must be defined as +ActionDispatch::Session::MyCustomStore+.
+This custom store must be defined as +ActionDispatch::Session::MyCustomStore+. In addition to symbols, they can also be objects implementing a certain API, like +ActiveRecord::SessionStore+, in which case no special namespace is required.
 
 * +config.threadsafe!+ enables +allow_concurrency+, +cache_classes+, +dependency_loading+ and +preload_frameworks+ to make the application threadsafe.
 
@@ -119,7 +112,9 @@ WARNING: Threadsafe operation is incompatible with the normal workings of develo
 
 * +config.time_zone+ sets the default time zone for the application and enables time zone awareness for Active Record.
 
-* +config.whiny_nils+ enables or disables warnings when any methods of nil are invoked. Defaults to _true_ in development and test environments.
+* +config.whiny_nils+ enables or disables warnings when a certain set of methods are invoked on +nil+ and it does not respond to them. Defaults to true in development and test environments.
+
+* +config.assets.enabled+ a flag that controls whether the asset pipeline is enabled. It is explicitly initialized in +config/application.rb+.
 
 h4. Configuring Generators
 

data/guides/source/contributing_to_ruby_on_rails.textile

@@ -232,11 +232,11 @@ You can also help out by examining pull requests that have been submitted to Rub
 $ git checkout -b testing_branch
 </shell>
 
-Then you can use their remote branch to update your codebase. For example, let's say the GitHub user JohnSmith has forked and pushed to the master branch located at https://github.com/JohnSmith/rails.
+Then you can use their remote branch to update your codebase. For example, let's say the GitHub user JohnSmith has forked and pushed to the topic branch located at https://github.com/JohnSmith/rails.
 
 <shell>
 $ git remote add JohnSmith git://github.com/JohnSmith/rails.git
-$ git pull JohnSmith master
+$ git pull JohnSmith topic
 </shell>
 
 After applying their branch, test it out! Here are some things to think about:
@@ -300,10 +300,16 @@ h4. Follow the Coding Conventions
 
 Rails follows a simple set of coding style conventions.
 
-* Two spaces, no tabs
-* Prefer +&amp;&amp;+/+||+ over +and+/+or+
-* +MyClass.my_method(my_arg)+ not +my_method( my_arg )+ or +my_method my_arg+
-* Follow the conventions you see used in the source already
+* Two spaces, no tabs.
+* No trailing whitespace. Blank lines should not have any space.
+* Indent after private/protected.
+* Prefer +&amp;&amp;+/+||+ over +and+/+or+.
+* Prefer class << self block over self.method for class methods.
+* +MyClass.my_method(my_arg)+ not +my_method( my_arg )+ or +my_method my_arg+.
+* a = b and not a=b.
+* Follow the conventions you see used in the source already.
+
+These are some guidelines and please use your best judgement in using them.
 
 h4. Sanity Check
 
@@ -344,20 +350,22 @@ Navigate to the Rails "GitHub repository":https://github.com/rails/rails and pre
 Add the new remote to your local repository on your local machine:
 
 <shell>
-$ git remote add mine https://&lt;your user name&gt;@github.com/&lt;your user name&gt;/rails.git
+$ git remote add mine https://<your user name>@github.com/<your user name>/rails.git
 </shell>
 
 Push to your remote:
 
 <shell>
-$ git push mine master
+$ git push mine my_new_branch
 </shell>
 
 h4. Issue a Pull Request
 
-Navigate to the Rails repository you just pushed to (e.g. https://github.com/&lt;your user name&gt;/rails) and press "Pull Request" in the upper right hand corner.
-  
-Ensure the changesets you introduced are included in the "Commits" tab and that the "Files Changed" incorporate all of your changes. 
+Navigate to the Rails repository you just pushed to (e.g. https://github.com/<your user name>/rails) and press "Pull Request" in the upper right hand corner.
+
+Write your branch name in branch field (is filled with master by default) and press "Update Commit Range"
+
+Ensure the changesets you introduced are included in the "Commits" tab and that the "Files Changed" incorporate all of your changes.
 
 Fill in some details about your potential patch including a meaningful title. When finished, press "Send pull request." Rails Core will be notified about your submission.
 
@@ -377,6 +385,7 @@ All contributions, either via master or docrails, get credit in "Rails Contribut
 
 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

data/guides/source/generators.textile

@@ -111,7 +111,6 @@ In order to understand what a generator template means, let's create the file +l
 
 <ruby>
 # Add initialization content here
-
 </ruby>
 
 And now let's change the generator to copy this template when invoked:
@@ -286,8 +285,8 @@ end
 Now, when the helper generator is invoked and TestUnit is configured as the test framework, it will try to invoke both +Rails::TestUnitGenerator+ and +TestUnit::MyHelperGenerator+. Since none of those are defined, we can tell our generator to invoke +TestUnit::Generators::HelperGenerator+ instead, which is defined since it's a Rails generator. To do that, we just need to add:
 
 <ruby>
-  # Search for :helper instead of :my_helper
-  hook_for :test_framework, :as => :helper
+# Search for :helper instead of :my_helper
+hook_for :test_framework, :as => :helper
 </ruby>
 
 And now you can re-run scaffold for another resource and see it generating tests as well!
@@ -412,7 +411,7 @@ h4. +plugin+
 +plugin+ will install a plugin into the current application.
 
 <ruby>
-  plugin("dynamic-form", :git => "git://github.com/rails/dynamic-form.git")
+plugin("dynamic-form", :git => "git://github.com/rails/dynamic-form.git")
 </ruby>
 
 Available options are:
@@ -441,13 +440,13 @@ Available options are:
 Any additional options passed to this method are put on the end of the line:
 
 <ruby>
-  gem("devise", :git => "git://github.com/plataformatec/devise", :branch => "master")
+gem("devise", :git => "git://github.com/plataformatec/devise", :branch => "master")
 </ruby>
 
 The above code will put the following line into +Gemfile+:
 
 <ruby>
-  gem "devise", :git => "git://github.com/plataformatec/devise", :branch => "master"
+gem "devise", :git => "git://github.com/plataformatec/devise", :branch => "master"
 </ruby>
 
 
@@ -456,7 +455,7 @@ h4. +add_source+
 Adds a specified source to +Gemfile+:
 
 <ruby>
-  add_source "http://gems.github.com"
+add_source "http://gems.github.com"
 </ruby>
 
 h4. +application+
@@ -464,7 +463,7 @@ h4. +application+
 Adds a line to +config/application.rb+ directly after the application class definition.
 
 <ruby>
-  application "config.asset_host = 'http://example.com'"
+application "config.asset_host = 'http://example.com'"
 </ruby>
 
 This method can also take a block:
@@ -490,10 +489,10 @@ h4. +git+
 Runs the specified git command:
 
 <ruby>
-  git :init
-  git :add => "."
-  git :commit => "-m First commit!"
-  git :add => "onefile.rb", :rm => "badfile.cxx"
+git :init
+git :add => "."
+git :commit => "-m First commit!"
+git :add => "onefile.rb", :rm => "badfile.cxx"
 </ruby>
 
 The values of the hash here being the arguments or options passed to the specific git command. As per the final example shown here, multiple git commands can be specified at a time, but the order of their running is not guaranteed to be the same as the order that they were specified in.
@@ -503,15 +502,15 @@ h4. +vendor+
 Places a file into +vendor+ which contains the specified code.
 
 <ruby>
-  vendor("sekrit.rb", '#top secret stuff')
+vendor("sekrit.rb", '#top secret stuff')
 </ruby>
 
 This method also takes a block:
 
 <ruby>
-  vendor("seeds.rb") do
-    "puts 'in ur app, seeding ur database'"
-  end
+vendor("seeds.rb") do
+  "puts 'in ur app, seeding ur database'"
+end
 </ruby>
 
 h4. +lib+
@@ -519,7 +518,7 @@ h4. +lib+
 Places a file into +lib+ which contains the specified code.
 
 <ruby>
-  lib("special.rb", 'p Rails.root')
+lib("special.rb", 'p Rails.root')
 </ruby>
 
 This method also takes a block:
@@ -535,7 +534,7 @@ h4. +rakefile+
 Creates a Rake file in the +lib/tasks+ directory of the application.
 
 <ruby>
-  rakefile("test.rake", 'hello there')
+rakefile("test.rake", 'hello there')
 </ruby>
 
 This method also takes a block:
@@ -555,7 +554,7 @@ h4. +initializer+
 Creates an initializer in the +config/initializers+ directory of the application:
 
 <ruby>
-  initializer("begin.rb", "puts 'this is the beginning'")
+initializer("begin.rb", "puts 'this is the beginning'")
 </ruby>
 
 This method also takes a block:
@@ -571,7 +570,7 @@ h4. +generate+
 Runs the specified generator where the first argument is the generator name and the remaining arguments are passed directly to the generator.
 
 <ruby>
-  generate("scaffold", "forums title:string description:text")
+generate("scaffold", "forums title:string description:text")
 </ruby>
 
 
@@ -580,7 +579,7 @@ h4. +rake+
 Runs the specified Rake task.
 
 <ruby>
-  rake("db:migrate")
+rake("db:migrate")
 </ruby>
 
 Available options are:
@@ -593,7 +592,7 @@ h4. +capify!+
 Runs the +capify+ command from Capistrano at the root of the application which generates Capistrano configuration.
 
 <ruby>
-  capify!
+capify!
 </ruby>
 
 h4. +route+
@@ -601,7 +600,7 @@ h4. +route+
 Adds text to the +config/routes.rb+ file:
 
 <ruby>
-  route("resources :people")
+route("resources :people")
 </ruby>
 
 h4. +readme+
@@ -609,7 +608,7 @@ h4. +readme+
 Output the contents of a file in the template's +source_path+, usually a README.
 
 <ruby>
-  readme("README")
+readme("README")
 </ruby>
 
 h3. Changelog