rails 4.0.13 → 4.1.16
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +22 -17
- data/guides/CHANGELOG.md +68 -34
- data/guides/assets/images/edge_badge.png +0 -0
- data/guides/assets/images/feature_tile.gif +0 -0
- data/guides/assets/images/footer_tile.gif +0 -0
- data/guides/assets/images/fxn.png +0 -0
- data/guides/assets/images/getting_started/article_with_comments.png +0 -0
- data/guides/assets/images/getting_started/challenge.png +0 -0
- data/guides/assets/images/getting_started/confirm_dialog.png +0 -0
- data/guides/assets/images/getting_started/forbidden_attributes_for_new_article.png +0 -0
- data/guides/assets/images/getting_started/form_with_errors.png +0 -0
- data/guides/assets/images/getting_started/index_action_with_edit_link.png +0 -0
- data/guides/assets/images/getting_started/new_article.png +0 -0
- data/guides/assets/images/getting_started/rails_welcome.png +0 -0
- data/guides/assets/images/getting_started/routing_error_no_controller.png +0 -0
- data/guides/assets/images/getting_started/routing_error_no_route_matches.png +0 -0
- data/guides/assets/images/getting_started/show_action_for_articles.png +0 -0
- data/guides/assets/images/getting_started/template_is_missing_articles_new.png +0 -0
- data/guides/assets/images/getting_started/unknown_action_create_for_articles.png +0 -0
- data/guides/assets/images/getting_started/unknown_action_new_for_articles.png +0 -0
- data/guides/assets/images/header_tile.gif +0 -0
- data/guides/assets/images/icons/README +1 -1
- data/guides/assets/images/icons/callouts/11.png +0 -0
- data/guides/assets/images/icons/callouts/12.png +0 -0
- data/guides/assets/images/icons/callouts/13.png +0 -0
- data/guides/assets/images/icons/callouts/15.png +0 -0
- data/guides/assets/images/icons/caution.png +0 -0
- data/guides/assets/images/icons/example.png +0 -0
- data/guides/assets/images/radar.png +0 -0
- data/guides/assets/images/rails4_features.png +0 -0
- data/guides/assets/images/rails_guides_kindle_cover.jpg +0 -0
- data/guides/assets/images/vijaydev.jpg +0 -0
- data/guides/assets/javascripts/guides.js +30 -34
- data/guides/assets/stylesheets/main.css +2 -1
- data/guides/assets/stylesheets/print.css +1 -1
- data/guides/bug_report_templates/action_controller_gem.rb +9 -4
- data/guides/bug_report_templates/action_controller_master.rb +4 -2
- data/guides/bug_report_templates/active_record_gem.rb +5 -2
- data/guides/bug_report_templates/active_record_master.rb +2 -1
- data/guides/bug_report_templates/generic_gem.rb +15 -0
- data/guides/bug_report_templates/generic_master.rb +26 -0
- data/guides/code/getting_started/Gemfile +21 -24
- data/guides/code/getting_started/Gemfile.lock +78 -73
- data/guides/code/getting_started/Rakefile +1 -1
- data/guides/code/getting_started/app/assets/javascripts/application.js +1 -2
- data/guides/code/getting_started/app/views/layouts/application.html.erb +2 -2
- data/guides/code/getting_started/config/environment.rb +1 -1
- data/guides/code/getting_started/config/environments/development.rb +2 -2
- data/guides/code/getting_started/config/environments/production.rb +3 -3
- data/guides/code/getting_started/config/environments/test.rb +2 -2
- data/guides/code/getting_started/config/initializers/secret_token.rb +1 -1
- data/guides/code/getting_started/config/initializers/session_store.rb +1 -1
- data/guides/code/getting_started/config/routes.rb +1 -1
- data/guides/code/getting_started/config.ru +1 -1
- data/guides/code/getting_started/public/404.html +2 -0
- data/guides/code/getting_started/public/422.html +2 -0
- data/guides/code/getting_started/public/500.html +2 -0
- data/guides/code/getting_started/test/test_helper.rb +0 -3
- data/guides/rails_guides/helpers.rb +3 -1
- data/guides/source/2_2_release_notes.md +2 -2
- data/guides/source/2_3_release_notes.md +8 -8
- data/guides/source/3_0_release_notes.md +2 -3
- data/guides/source/3_1_release_notes.md +2 -2
- data/guides/source/3_2_release_notes.md +12 -12
- data/guides/source/4_0_release_notes.md +79 -46
- data/guides/source/4_1_release_notes.md +731 -0
- data/guides/source/_welcome.html.erb +5 -2
- data/guides/source/action_controller_overview.md +189 -40
- data/guides/source/action_mailer_basics.md +27 -27
- data/guides/source/action_view_overview.md +131 -20
- data/guides/source/active_model_basics.md +6 -6
- data/guides/source/active_record_basics.md +15 -15
- data/guides/source/active_record_callbacks.md +18 -16
- data/guides/source/active_record_querying.md +93 -51
- data/guides/source/active_record_validations.md +26 -24
- data/guides/source/active_support_core_extensions.md +72 -118
- data/guides/source/active_support_instrumentation.md +13 -4
- data/guides/source/api_documentation_guidelines.md +104 -6
- data/guides/source/asset_pipeline.md +573 -244
- data/guides/source/association_basics.md +94 -22
- data/guides/source/caching_with_rails.md +15 -6
- data/guides/source/command_line.md +55 -46
- data/guides/source/configuring.md +248 -52
- data/guides/source/contributing_to_ruby_on_rails.md +18 -17
- data/guides/source/credits.html.erb +2 -2
- data/guides/source/debugging_rails_applications.md +39 -8
- data/guides/source/development_dependencies_install.md +91 -8
- data/guides/source/documents.yaml +4 -0
- data/guides/source/engines.md +678 -232
- data/guides/source/form_helpers.md +53 -35
- data/guides/source/generators.md +19 -15
- data/guides/source/getting_started.md +758 -497
- data/guides/source/i18n.md +64 -28
- data/guides/source/index.html.erb +1 -1
- data/guides/source/initialization.md +155 -58
- data/guides/source/kindle/toc.html.erb +1 -1
- data/guides/source/layout.html.erb +2 -2
- data/guides/source/layouts_and_rendering.md +59 -26
- data/guides/source/maintenance_policy.md +3 -3
- data/guides/source/migrations.md +101 -62
- data/guides/source/nested_model_forms.md +3 -3
- data/guides/source/plugins.md +34 -31
- data/guides/source/rails_application_templates.md +27 -8
- data/guides/source/rails_on_rack.md +41 -58
- data/guides/source/routing.md +115 -104
- data/guides/source/ruby_on_rails_guides_guidelines.md +2 -2
- data/guides/source/security.md +81 -36
- data/guides/source/testing.md +56 -79
- data/guides/source/upgrading_ruby_on_rails.md +531 -21
- data/guides/source/working_with_javascript_in_rails.md +19 -11
- metadata +51 -23
- data/guides/assets/images/getting_started/forbidden_attributes_for_new_post.png +0 -0
- data/guides/assets/images/getting_started/new_post.png +0 -0
- data/guides/assets/images/getting_started/post_with_comments.png +0 -0
- data/guides/assets/images/getting_started/show_action_for_posts.png +0 -0
- data/guides/assets/images/getting_started/template_is_missing_posts_new.png +0 -0
- data/guides/assets/images/getting_started/undefined_method_post_path.png +0 -0
- data/guides/assets/images/getting_started/unknown_action_create_for_posts.png +0 -0
- data/guides/assets/images/getting_started/unknown_action_new_for_posts.png +0 -0
- data/guides/assets/images/jaimeiniesta.jpg +0 -0
- data/guides/source/kindle/KINDLE.md +0 -26
@@ -30,10 +30,10 @@ Configuring Rails Components
|
|
30
30
|
|
31
31
|
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.
|
32
32
|
|
33
|
-
For example, the
|
33
|
+
For example, the `config/application.rb` file includes this setting:
|
34
34
|
|
35
35
|
```ruby
|
36
|
-
config.
|
36
|
+
config.autoload_paths += %W(#{config.root}/extras)
|
37
37
|
```
|
38
38
|
|
39
39
|
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`:
|
@@ -66,6 +66,9 @@ These configuration methods are to be called on a `Rails::Railtie` object, such
|
|
66
66
|
|
67
67
|
* `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`.
|
68
68
|
|
69
|
+
* `config.beginning_of_week` sets the default beginning of week for the
|
70
|
+
application. Accepts a valid week day symbol (e.g. `:monday`).
|
71
|
+
|
69
72
|
* `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`, `:null_store`, or an object that implements the cache API. Defaults to `:file_store` if the directory `tmp/cache` exists, and to `:memory_store` otherwise.
|
70
73
|
|
71
74
|
* `config.colorize_logging` specifies whether or not to use ANSI color codes when logging information. Defaults to true.
|
@@ -97,15 +100,17 @@ These configuration methods are to be called on a `Rails::Railtie` object, such
|
|
97
100
|
|
98
101
|
* `config.file_watcher` the class used to detect file updates in the filesystem when `config.reload_classes_only_on_change` is true. Must conform to `ActiveSupport::FileUpdateChecker` API.
|
99
102
|
|
100
|
-
* `config.filter_parameters` used for filtering out the parameters that
|
103
|
+
* `config.filter_parameters` used for filtering out the parameters that
|
104
|
+
you don't want shown in the logs, such as passwords or credit card
|
105
|
+
numbers. New applications filter out passwords by adding the following `config.filter_parameters+=[:password]` in `config/initializers/filter_parameter_logging.rb`.
|
101
106
|
|
102
107
|
* `config.force_ssl` forces all requests to be under HTTPS protocol by using `ActionDispatch::SSL` middleware.
|
103
108
|
|
104
|
-
* `config.log_formatter` defines the formatter of the Rails logger. This option defaults to
|
109
|
+
* `config.log_formatter` defines the formatter of the Rails logger. This option defaults to an instance of `ActiveSupport::Logger::SimpleFormatter` for all modes except production, where it defaults to `Logger::Formatter`.
|
105
110
|
|
106
111
|
* `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`.
|
107
112
|
|
108
|
-
* `config.log_tags` accepts a list of methods that respond to `request` object. This makes it easy to tag log lines with debug information like subdomain and request id
|
113
|
+
* `config.log_tags` accepts a list of methods that respond to `request` object. This makes it easy to tag log lines with debug information like subdomain and request id - both very helpful in debugging multi-user production applications.
|
109
114
|
|
110
115
|
* `config.logger` accepts a logger conforming to the interface of Log4r or the default Ruby `Logger` class. Defaults to an instance of `ActiveSupport::Logger`, with auto flushing off in production mode.
|
111
116
|
|
@@ -115,7 +120,7 @@ These configuration methods are to be called on a `Rails::Railtie` object, such
|
|
115
120
|
|
116
121
|
* `config.secret_key_base` 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_key_base` initialized to a random key in `config/initializers/secret_token.rb`.
|
117
122
|
|
118
|
-
* `config.serve_static_assets` configures Rails itself to serve static assets. Defaults to true, but in the production environment is turned off as the server software (e.g. Nginx or Apache) used to run the application should serve static assets instead. Unlike the default setting set this to true when running (absolutely not recommended!) or testing your app in production mode using WEBrick. Otherwise you won
|
123
|
+
* `config.serve_static_assets` configures Rails itself to serve static assets. Defaults to true, but in the production environment is turned off as the server software (e.g. Nginx or Apache) used to run the application should serve static assets instead. Unlike the default setting set this to true when running (absolutely not recommended!) or testing your app in production mode using WEBrick. Otherwise you won't be able use page caching and requests for files that exist regularly under the public directory will anyway hit your Rails app.
|
119
124
|
|
120
125
|
* `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` which is the default, `:mem_cache_store`, and `:disabled`. The last one tells Rails not to deal with sessions. Custom session stores can also be specified:
|
121
126
|
|
@@ -127,15 +132,14 @@ These configuration methods are to be called on a `Rails::Railtie` object, such
|
|
127
132
|
|
128
133
|
* `config.time_zone` sets the default time zone for the application and enables time zone awareness for Active Record.
|
129
134
|
|
130
|
-
* `config.beginning_of_week` sets the default beginning of week for the application. Accepts a valid week day symbol (e.g. `:monday`).
|
131
|
-
|
132
|
-
* `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.
|
133
|
-
|
134
135
|
### Configuring Assets
|
135
136
|
|
136
|
-
* `config.assets.enabled` a flag that controls whether the asset
|
137
|
+
* `config.assets.enabled` a flag that controls whether the asset
|
138
|
+
pipeline is enabled. It is set to true by default.
|
139
|
+
|
140
|
+
*`config.assets.raise_runtime_errors`* Set this flag to `true` to enable additional runtime error checking. Recommended in `config/environments/development.rb` to minimize unexpected behavior when deploying to `production`.
|
137
141
|
|
138
|
-
* `config.assets.compress` a flag that enables the compression of compiled assets. It is explicitly set to true in `config/production.rb`.
|
142
|
+
* `config.assets.compress` a flag that enables the compression of compiled assets. It is explicitly set to true in `config/environments/production.rb`.
|
139
143
|
|
140
144
|
* `config.assets.css_compressor` defines the CSS compressor to use. It is set by default by `sass-rails`. The unique alternative value at the moment is `:yui`, which uses the `yui-compressor` gem.
|
141
145
|
|
@@ -195,7 +199,7 @@ Every Rails application comes with a standard set of middleware which it uses in
|
|
195
199
|
* `Rack::Lock` wraps the app in mutex so it can only be called by a single thread at a time. Only enabled when `config.cache_classes` is `false`.
|
196
200
|
* `ActiveSupport::Cache::Strategy::LocalCache` serves as a basic memory backed cache. This cache is not thread safe and is intended only for serving as a temporary memory cache for a single thread.
|
197
201
|
* `Rack::Runtime` sets an `X-Runtime` header, containing the time (in seconds) taken to execute the request.
|
198
|
-
* `Rails::Rack::Logger` notifies the logs that the request has
|
202
|
+
* `Rails::Rack::Logger` notifies the logs that the request has begun. After request is complete, flushes all the logs.
|
199
203
|
* `ActionDispatch::ShowExceptions` rescues any exception returned by the application and renders nice exception pages if the request is local or if `config.consider_all_requests_local` is set to `true`. If `config.action_dispatch.show_exceptions` is set to `false`, exceptions will be raised regardless.
|
200
204
|
* `ActionDispatch::RequestId` makes a unique X-Request-Id header available to the response and enables the `ActionDispatch::Request#uuid` method.
|
201
205
|
* `ActionDispatch::RemoteIp` checks for IP spoofing attacks and gets valid `client_ip` from request headers. Configurable with the `config.action_dispatch.ip_spoofing_check`, and `config.action_dispatch.trusted_proxies` options.
|
@@ -266,9 +270,11 @@ All these configuration options are delegated to the `I18n` library.
|
|
266
270
|
|
267
271
|
* `config.active_record.table_name_suffix` lets you set a global string to be appended to table names. If you set this to `_northwest`, then the Customer class will look for `customers_northwest` as its table. The default is an empty string.
|
268
272
|
|
273
|
+
* `config.active_record.schema_migrations_table_name` lets you set a string to be used as the name of the schema migrations table.
|
274
|
+
|
269
275
|
* `config.active_record.pluralize_table_names` specifies whether Rails will look for singular or plural table names in the database. If set to true (the default), then the Customer class will use the `customers` table. If set to false, then the Customer class will use the `customer` table.
|
270
276
|
|
271
|
-
* `config.active_record.default_timezone` determines whether to use `Time.local` (if set to `:local`) or `Time.utc` (if set to `:utc`) when pulling dates and times from the database. The default is `:utc
|
277
|
+
* `config.active_record.default_timezone` determines whether to use `Time.local` (if set to `:local`) or `Time.utc` (if set to `:utc`) when pulling dates and times from the database. The default is `:utc`.
|
272
278
|
|
273
279
|
* `config.active_record.schema_format` controls the format for dumping the database schema to a file. The options are `:ruby` (the default) for a database-independent version that depends on migrations, or `:sql` for a set of (potentially database-dependent) SQL statements.
|
274
280
|
|
@@ -278,6 +284,20 @@ All these configuration options are delegated to the `I18n` library.
|
|
278
284
|
|
279
285
|
* `config.active_record.cache_timestamp_format` controls the format of the timestamp value in the cache key. Default is `:number`.
|
280
286
|
|
287
|
+
* `config.active_record.record_timestamps` is a boolean value which controls whether or not timestamping of `create` and `update` operations on a model occur. The default value is `true`.
|
288
|
+
|
289
|
+
* `config.active_record.partial_writes` is a boolean value and controls whether or not partial writes are used (i.e. whether updates only set attributes that are dirty). Note that when using partial writes, you should also use optimistic locking `config.active_record.lock_optimistically` since concurrent updates may write attributes based on a possibly stale read state. The default value is `true`.
|
290
|
+
|
291
|
+
* `config.active_record.attribute_types_cached_by_default` sets the attribute types that `ActiveRecord::AttributeMethods` will cache by default on reads. The default is `[:datetime, :timestamp, :time, :date]`.
|
292
|
+
|
293
|
+
* `config.active_record.maintain_test_schema` is a boolean value which controls whether Active Record should try to keep your test database schema up-to-date with `db/schema.rb` (or `db/structure.sql`) when you run your tests. The default is true.
|
294
|
+
|
295
|
+
* `config.active_record.dump_schema_after_migration` is a flag which
|
296
|
+
controls whether or not schema dump should happen (`db/schema.rb` or
|
297
|
+
`db/structure.sql`) when you run migrations. This is set to false in
|
298
|
+
`config/environments/production.rb` which is generated by Rails. The
|
299
|
+
default value is true if this configuration is not set.
|
300
|
+
|
281
301
|
The MySQL adapter adds one additional configuration option:
|
282
302
|
|
283
303
|
* `ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans` controls whether Active Record will consider all `tinyint(1)` columns in a MySQL database to be booleans and is true by default.
|
@@ -304,7 +324,7 @@ The schema dumper adds one additional configuration option:
|
|
304
324
|
|
305
325
|
* `config.action_controller.allow_forgery_protection` enables or disables CSRF protection. By default this is `false` in test mode and `true` in all other modes.
|
306
326
|
|
307
|
-
* `config.action_controller.relative_url_root` can be used to tell Rails that you are deploying to a subdirectory. The default is `ENV['RAILS_RELATIVE_URL_ROOT']`.
|
327
|
+
* `config.action_controller.relative_url_root` can be used to tell Rails that you are [deploying to a subdirectory](configuring.html#deploy-to-a-subdirectory-relative-url-root). The default is `ENV['RAILS_RELATIVE_URL_ROOT']`.
|
308
328
|
|
309
329
|
* `config.action_controller.permit_all_parameters` sets all the parameters for mass assignment to be permitted by default. The default value is `false`.
|
310
330
|
|
@@ -326,6 +346,22 @@ The schema dumper adds one additional configuration option:
|
|
326
346
|
|
327
347
|
* `config.action_dispatch.tld_length` sets the TLD (top-level domain) length for the application. Defaults to `1`.
|
328
348
|
|
349
|
+
* `config.action_dispatch.http_auth_salt` sets the HTTP Auth salt value. Defaults
|
350
|
+
to `'http authentication'`.
|
351
|
+
|
352
|
+
* `config.action_dispatch.signed_cookie_salt` sets the signed cookies salt value.
|
353
|
+
Defaults to `'signed cookie'`.
|
354
|
+
|
355
|
+
* `config.action_dispatch.encrypted_cookie_salt` sets the encrypted cookies salt
|
356
|
+
value. Defaults to `'encrypted cookie'`.
|
357
|
+
|
358
|
+
* `config.action_dispatch.encrypted_signed_cookie_salt` sets the signed
|
359
|
+
encrypted cookies salt value. Defaults to `'signed encrypted cookie'`.
|
360
|
+
|
361
|
+
* `config.action_dispatch.perform_deep_munge` configures whether `deep_munge`
|
362
|
+
method should be performed on the parameters. See [Security Guide](security.html#unsafe-query-generation)
|
363
|
+
for more information. It defaults to true.
|
364
|
+
|
329
365
|
* `ActionDispatch::Callbacks.before` takes a block of code to run before the request.
|
330
366
|
|
331
367
|
* `ActionDispatch::Callbacks.to_prepare` takes a block to run after `ActionDispatch::Callbacks.before`, but before the request. Runs for every request in `development` mode, but only once for `production` or environments with `cache_classes` set to `true`.
|
@@ -348,7 +384,7 @@ The schema dumper adds one additional configuration option:
|
|
348
384
|
|
349
385
|
* `config.action_view.logger` accepts a logger conforming to the interface of Log4r or the default Ruby Logger class, which is then used to log information from Action View. Set to `nil` to disable logging.
|
350
386
|
|
351
|
-
* `config.action_view.erb_trim_mode` gives the trim mode to be used by ERB. It defaults to `'-'
|
387
|
+
* `config.action_view.erb_trim_mode` gives the trim mode to be used by ERB. It defaults to `'-'`, which turns on trimming of tail spaces and newline when using `<%= -%>` or `<%= =%>`. See the [Erubis documentation](http://www.kuwata-lab.com/erubis/users-guide.06.html#topics-trimspaces) for more information.
|
352
388
|
|
353
389
|
* `config.action_view.embed_authenticity_token_in_remote_forms` allows you to set the default behavior for `authenticity_token` in forms with `:remote => true`. By default it's set to false, which means that remote forms will not include `authenticity_token`, which is helpful when you're fragment-caching the form. Remote forms get the authenticity from the `meta` tag, so embedding is unnecessary unless you support browsers without JavaScript. In such case you can either pass `:authenticity_token => true` as a form option or set this config setting to `true`
|
354
390
|
|
@@ -382,17 +418,25 @@ There are a number of settings available on `config.action_mailer`:
|
|
382
418
|
|
383
419
|
* `config.action_mailer.raise_delivery_errors` specifies whether to raise an error if email delivery cannot be completed. It defaults to true.
|
384
420
|
|
385
|
-
* `config.action_mailer.delivery_method` defines the delivery method
|
421
|
+
* `config.action_mailer.delivery_method` defines the delivery method and defaults to `:smtp`. See the [configuration section in the Action Mailer guide](http://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration) for more info.
|
386
422
|
|
387
423
|
* `config.action_mailer.perform_deliveries` specifies whether mail will actually be delivered and is true by default. It can be convenient to set it to false for testing.
|
388
424
|
|
389
425
|
* `config.action_mailer.default_options` configures Action Mailer defaults. Use to set options like `from` or `reply_to` for every mailer. These default to:
|
390
426
|
|
391
427
|
```ruby
|
392
|
-
:
|
393
|
-
:
|
394
|
-
:
|
395
|
-
:
|
428
|
+
mime_version: "1.0",
|
429
|
+
charset: "UTF-8",
|
430
|
+
content_type: "text/plain",
|
431
|
+
parts_order: ["text/plain", "text/enriched", "text/html"]
|
432
|
+
```
|
433
|
+
|
434
|
+
Assign a hash to set additional options:
|
435
|
+
|
436
|
+
```ruby
|
437
|
+
config.action_mailer.default_options = {
|
438
|
+
from: "noreply@example.com"
|
439
|
+
}
|
396
440
|
```
|
397
441
|
|
398
442
|
* `config.action_mailer.observers` registers observers which will be notified when mail is delivered.
|
@@ -417,6 +461,8 @@ There are a few configuration options available in Active Support:
|
|
417
461
|
|
418
462
|
* `config.active_support.use_standard_json_time_format` enables or disables serializing dates to ISO 8601 format. Defaults to `true`.
|
419
463
|
|
464
|
+
* `config.active_support.time_precision` sets the precision of JSON encoded time values. Defaults to `3`.
|
465
|
+
|
420
466
|
* `ActiveSupport::Logger.silencer` is set to `false` to disable the ability to silence logging in a block. The default is `true`.
|
421
467
|
|
422
468
|
* `ActiveSupport::Cache::Store.logger` specifies the logger to use within cache store operations.
|
@@ -427,17 +473,133 @@ There are a few configuration options available in Active Support:
|
|
427
473
|
|
428
474
|
* `ActiveSupport::Deprecation.silenced` sets whether or not to display deprecation warnings.
|
429
475
|
|
430
|
-
* `ActiveSupport::Logger.silencer` is set to `false` to disable the ability to silence logging in a block. The default is `true`.
|
431
476
|
|
432
477
|
### Configuring a Database
|
433
478
|
|
434
|
-
Just about every Rails application will interact with a database.
|
479
|
+
Just about every Rails application will interact with a database. You can connect to the database by setting an environment variable `ENV['DATABASE_URL']` or by using a configuration file called `config/database.yml`.
|
480
|
+
|
481
|
+
Using the `config/database.yml` file you can specify all the information needed to access your database:
|
482
|
+
|
483
|
+
```yaml
|
484
|
+
development:
|
485
|
+
adapter: postgresql
|
486
|
+
database: blog_development
|
487
|
+
pool: 5
|
488
|
+
```
|
489
|
+
|
490
|
+
This will connect to the database named `blog_development` using the `postgresql` adapter. This same information can be stored in a URL and provided via an environment variable like this:
|
491
|
+
|
492
|
+
```ruby
|
493
|
+
> puts ENV['DATABASE_URL']
|
494
|
+
postgresql://localhost/blog_development?pool=5
|
495
|
+
```
|
496
|
+
|
497
|
+
The `config/database.yml` file contains sections for three different environments in which Rails can run by default:
|
435
498
|
|
436
499
|
* The `development` environment is used on your development/local computer as you interact manually with the application.
|
437
500
|
* The `test` environment is used when running automated tests.
|
438
501
|
* The `production` environment is used when you deploy your application for the world to use.
|
439
502
|
|
440
|
-
|
503
|
+
If you wish, you can manually specify a URL inside of your `config/database.yml`
|
504
|
+
|
505
|
+
```
|
506
|
+
development:
|
507
|
+
url: postgresql://localhost/blog_development?pool=5
|
508
|
+
```
|
509
|
+
|
510
|
+
The `config/database.yml` file can contain ERB tags `<%= %>`. Anything in the tags will be evaluated as Ruby code. You can use this to pull out data from an environment variable or to perform calculations to generate the needed connection information.
|
511
|
+
|
512
|
+
|
513
|
+
TIP: You don't have to update the database configurations manually. If you look at the options of the application generator, you will see that one of the options is named `--database`. This option allows you to choose an adapter from a list of the most used relational databases. You can even run the generator repeatedly: `cd .. && rails new blog --database=mysql`. When you confirm the overwriting of the `config/database.yml` file, your application will be configured for MySQL instead of SQLite. Detailed examples of the common database connections are below.
|
514
|
+
|
515
|
+
|
516
|
+
### Connection Preference
|
517
|
+
|
518
|
+
Since there are two ways to set your connection, via environment variable it is important to understand how the two can interact.
|
519
|
+
|
520
|
+
If you have an empty `config/database.yml` file but your `ENV['DATABASE_URL']` is present, then Rails will connect to the database via your environment variable:
|
521
|
+
|
522
|
+
```
|
523
|
+
$ cat config/database.yml
|
524
|
+
|
525
|
+
$ echo $DATABASE_URL
|
526
|
+
postgresql://localhost/my_database
|
527
|
+
```
|
528
|
+
|
529
|
+
If you have a `config/database.yml` but no `ENV['DATABASE_URL']` then this file will be used to connect to your database:
|
530
|
+
|
531
|
+
```
|
532
|
+
$ cat config/database.yml
|
533
|
+
development:
|
534
|
+
adapter: postgresql
|
535
|
+
database: my_database
|
536
|
+
host: localhost
|
537
|
+
|
538
|
+
$ echo $DATABASE_URL
|
539
|
+
```
|
540
|
+
|
541
|
+
If you have both `config/database.yml` and `ENV['DATABASE_URL']` set then Rails will merge the configuration together. To better understand this we must see some examples.
|
542
|
+
|
543
|
+
When duplicate connection information is provided the environment variable will take precedence:
|
544
|
+
|
545
|
+
```
|
546
|
+
$ cat config/database.yml
|
547
|
+
development:
|
548
|
+
adapter: sqlite3
|
549
|
+
database: NOT_my_database
|
550
|
+
host: localhost
|
551
|
+
|
552
|
+
$ echo $DATABASE_URL
|
553
|
+
postgresql://localhost/my_database
|
554
|
+
|
555
|
+
$ bin/rails runner 'puts ActiveRecord::Base.connections'
|
556
|
+
{"development"=>{"adapter"=>"postgresql", "host"=>"localhost", "database"=>"my_database"}}
|
557
|
+
```
|
558
|
+
|
559
|
+
Here the adapter, host, and database match the information in `ENV['DATABASE_URL']`.
|
560
|
+
|
561
|
+
If non-duplicate information is provided you will get all unique values, environment variable still takes precedence in cases of any conflicts.
|
562
|
+
|
563
|
+
```
|
564
|
+
$ cat config/database.yml
|
565
|
+
development:
|
566
|
+
adapter: sqlite3
|
567
|
+
pool: 5
|
568
|
+
|
569
|
+
$ echo $DATABASE_URL
|
570
|
+
postgresql://localhost/my_database
|
571
|
+
|
572
|
+
$ bin/rails runner 'puts ActiveRecord::Base.connections'
|
573
|
+
{"development"=>{"adapter"=>"postgresql", "host"=>"localhost", "database"=>"my_database", "pool"=>5}}
|
574
|
+
```
|
575
|
+
|
576
|
+
Since pool is not in the `ENV['DATABASE_URL']` provided connection information its information is merged in. Since `adapter` is duplicate, the `ENV['DATABASE_URL']` connection information wins.
|
577
|
+
|
578
|
+
The only way to explicitly not use the connection information in `ENV['DATABASE_URL']` is to specify an explicit URL connection using the `"url"` sub key:
|
579
|
+
|
580
|
+
```
|
581
|
+
$ cat config/database.yml
|
582
|
+
development:
|
583
|
+
url: sqlite3:NOT_my_database
|
584
|
+
|
585
|
+
$ echo $DATABASE_URL
|
586
|
+
postgresql://localhost/my_database
|
587
|
+
|
588
|
+
$ bin/rails runner 'puts ActiveRecord::Base.connections'
|
589
|
+
{"development"=>{"adapter"=>"sqlite3", "database"=>"NOT_my_database"}}
|
590
|
+
```
|
591
|
+
|
592
|
+
Here the connection information in `ENV['DATABASE_URL']` is ignored, note the different adapter and database name.
|
593
|
+
|
594
|
+
Since it is possible to embed ERB in your `config/database.yml` it is best practice to explicitly show you are using the `ENV['DATABASE_URL']` to connect to your database. This is especially useful in production since you should not commit secrets like your database password into your source control (such as Git).
|
595
|
+
|
596
|
+
```
|
597
|
+
$ cat config/database.yml
|
598
|
+
production:
|
599
|
+
url: <%= ENV['DATABASE_URL'] %>
|
600
|
+
```
|
601
|
+
|
602
|
+
Now the behavior is clear, that we are only using the connection information in `ENV['DATABASE_URL']`.
|
441
603
|
|
442
604
|
#### Configuring an SQLite3 Database
|
443
605
|
|
@@ -535,10 +697,47 @@ Change the username and password in the `development` section as appropriate.
|
|
535
697
|
|
536
698
|
By default Rails ships with three environments: "development", "test", and "production". While these are sufficient for most use cases, there are circumstances when you want more environments.
|
537
699
|
|
538
|
-
Imagine you have a server which mirrors the production environment but is only used for testing. Such a server is commonly called a "staging server". To define an environment called "staging" for this server just
|
700
|
+
Imagine you have a server which mirrors the production environment but is only used for testing. Such a server is commonly called a "staging server". To define an environment called "staging" for this server, just create a file called `config/environments/staging.rb`. Please use the contents of any existing file in `config/environments` as a starting point and make the necessary changes from there.
|
701
|
+
|
702
|
+
That environment is no different than the default ones, start a server with `rails server -e staging`, a console with `rails console staging`, `Rails.env.staging?` works, etc.
|
703
|
+
|
704
|
+
|
705
|
+
### Deploy to a subdirectory (relative url root)
|
706
|
+
|
707
|
+
By default Rails expects that your application is running at the root
|
708
|
+
(eg. `/`). This section explains how to run your application inside a directory.
|
709
|
+
|
710
|
+
Let's assume we want to deploy our application to "/app1". Rails needs to know
|
711
|
+
this directory to generate the appropriate routes:
|
712
|
+
|
713
|
+
```ruby
|
714
|
+
config.relative_url_root = "/app1"
|
715
|
+
```
|
716
|
+
|
717
|
+
alternatively you can set the `RAILS_RELATIVE_URL_ROOT` environment
|
718
|
+
variable.
|
719
|
+
|
720
|
+
Rails will now prepend "/app1" when generating links.
|
721
|
+
|
722
|
+
#### Using Passenger
|
723
|
+
|
724
|
+
Passenger makes it easy to run your application in a subdirectory. You can find
|
725
|
+
the relevant configuration in the
|
726
|
+
[passenger manual](http://www.modrails.com/documentation/Users%20guide%20Apache.html#deploying_rails_to_sub_uri).
|
727
|
+
|
728
|
+
#### Using a Reverse Proxy
|
729
|
+
|
730
|
+
TODO
|
539
731
|
|
540
|
-
|
732
|
+
#### Considerations when deploying to a subdirectory
|
541
733
|
|
734
|
+
Deploying to a subdirectory in production has implications on various parts of
|
735
|
+
Rails.
|
736
|
+
|
737
|
+
* development environment:
|
738
|
+
* testing environment:
|
739
|
+
* serving static assets:
|
740
|
+
* asset pipeline:
|
542
741
|
|
543
742
|
Rails Environment Settings
|
544
743
|
--------------------------
|
@@ -547,7 +746,7 @@ Some parts of Rails can also be configured externally by supplying environment v
|
|
547
746
|
|
548
747
|
* `ENV["RAILS_ENV"]` defines the Rails environment (production, development, test, and so on) that Rails will run under.
|
549
748
|
|
550
|
-
* `ENV["RAILS_RELATIVE_URL_ROOT"]` is used by the routing code to recognize URLs when you deploy your application to a subdirectory.
|
749
|
+
* `ENV["RAILS_RELATIVE_URL_ROOT"]` is used by the routing code to recognize URLs when you [deploy your application to a subdirectory](configuring.html#deploy-to-a-subdirectory-relative-url-root).
|
551
750
|
|
552
751
|
* `ENV["RAILS_CACHE_ID"]` and `ENV["RAILS_APP_VERSION"]` are used to generate expanded cache keys in Rails' caching code. This allows you to have multiple separate caches from the same application.
|
553
752
|
|
@@ -600,17 +799,17 @@ WARNING: Some parts of your application, notably routing, are not yet set up at
|
|
600
799
|
|
601
800
|
### `Rails::Railtie#initializer`
|
602
801
|
|
603
|
-
Rails has several initializers that run on startup that are all defined by using the `initializer` method from `Rails::Railtie`. Here's an example of the `
|
802
|
+
Rails has several initializers that run on startup that are all defined by using the `initializer` method from `Rails::Railtie`. Here's an example of the `set_helpers_path` initializer from Action Controller:
|
604
803
|
|
605
804
|
```ruby
|
606
|
-
initializer "
|
607
|
-
|
805
|
+
initializer "action_controller.set_helpers_path" do |app|
|
806
|
+
ActionController::Helpers.helpers_path = app.helpers_paths
|
608
807
|
end
|
609
808
|
```
|
610
809
|
|
611
810
|
The `initializer` method takes three arguments with the first being the name for the initializer and the second being an options hash (not shown here) and the third being a block. The `:before` key in the options hash can be specified to specify which initializer this new initializer must run before, and the `:after` key will specify which initializer to run this initializer _after_.
|
612
811
|
|
613
|
-
Initializers defined using the `initializer` method will be
|
812
|
+
Initializers defined using the `initializer` method will be run in the order they are defined in, with the exception of ones that use the `:before` or `:after` methods.
|
614
813
|
|
615
814
|
WARNING: You may put your initializer before or after any other initializer in the chain, as long as it is logical. Say you have 4 initializers called "one" through "four" (defined in that order) and you define "four" to go _before_ "four" but _after_ "three", that just isn't logical and Rails will not be able to determine your initializer order.
|
616
815
|
|
@@ -630,7 +829,7 @@ Below is a comprehensive list of all the initializers found in Rails in the orde
|
|
630
829
|
|
631
830
|
* `initialize_cache` If `Rails.cache` isn't set yet, initializes the cache by referencing the value in `config.cache_store` and stores the outcome as `Rails.cache`. If this object responds to the `middleware` method, its middleware is inserted before `Rack::Runtime` in the middleware stack.
|
632
831
|
|
633
|
-
* `set_clear_dependencies_hook` Provides a hook for `active_record.set_dispatch_hooks` to use, which will run before this initializer. This initializer
|
832
|
+
* `set_clear_dependencies_hook` Provides a hook for `active_record.set_dispatch_hooks` to use, which will run before this initializer. This initializer - which runs only if `cache_classes` is set to `false` - uses `ActionDispatch::Callbacks.after` to remove the constants which have been referenced during the request from the object space so that they will be reloaded during the following request.
|
634
833
|
|
635
834
|
* `initialize_dependency_mechanism` If `config.cache_classes` is true, configures `ActiveSupport::Dependencies.mechanism` to `require` dependencies rather than `load` them.
|
636
835
|
|
@@ -638,20 +837,6 @@ Below is a comprehensive list of all the initializers found in Rails in the orde
|
|
638
837
|
|
639
838
|
* `i18n.callbacks` In the development environment, sets up a `to_prepare` callback which will call `I18n.reload!` if any of the locales have changed since the last request. In production mode this callback will only run on the first request.
|
640
839
|
|
641
|
-
* `active_support.initialize_whiny_nils` Requires `active_support/whiny_nil` if `config.whiny_nils` is true. This file will output errors such as:
|
642
|
-
|
643
|
-
```
|
644
|
-
Called id for nil, which would mistakenly be 4 — if you really wanted the id of nil, use object_id
|
645
|
-
```
|
646
|
-
|
647
|
-
And:
|
648
|
-
|
649
|
-
```
|
650
|
-
You have a nil object when you didn't expect it!
|
651
|
-
You might have expected an instance of Array.
|
652
|
-
The error occurred while evaluating nil.each
|
653
|
-
```
|
654
|
-
|
655
840
|
* `active_support.deprecation_behavior` Sets up deprecation reporting for environments, defaulting to `:log` for development, `:notify` for production and `:stderr` for test. If a value isn't set for `config.active_support.deprecation` then this initializer will prompt the user to configure this line in the current environment's `config/environments` file. Can be set to an array of values.
|
656
841
|
|
657
842
|
* `active_support.initialize_time_zone` Sets the default time zone for the application based on the `config.time_zone` setting, which defaults to "UTC".
|
@@ -662,9 +847,9 @@ Below is a comprehensive list of all the initializers found in Rails in the orde
|
|
662
847
|
|
663
848
|
* `action_view.set_configs` Sets up Action View by using the settings in `config.action_view` by `send`'ing the method names as setters to `ActionView::Base` and passing the values through.
|
664
849
|
|
665
|
-
* `action_controller.logger` Sets `ActionController::Base.logger`
|
850
|
+
* `action_controller.logger` Sets `ActionController::Base.logger` - if it's not already set - to `Rails.logger`.
|
666
851
|
|
667
|
-
* `action_controller.initialize_framework_caches` Sets `ActionController::Base.cache_store`
|
852
|
+
* `action_controller.initialize_framework_caches` Sets `ActionController::Base.cache_store` - if it's not already set - to `Rails.cache`.
|
668
853
|
|
669
854
|
* `action_controller.set_configs` Sets up Action Controller by using the settings in `config.action_controller` by `send`'ing the method names as setters to `ActionController::Base` and passing the values through.
|
670
855
|
|
@@ -672,7 +857,7 @@ Below is a comprehensive list of all the initializers found in Rails in the orde
|
|
672
857
|
|
673
858
|
* `active_record.initialize_timezone` Sets `ActiveRecord::Base.time_zone_aware_attributes` to true, as well as setting `ActiveRecord::Base.default_timezone` to UTC. When attributes are read from the database, they will be converted into the time zone specified by `Time.zone`.
|
674
859
|
|
675
|
-
* `active_record.logger` Sets `ActiveRecord::Base.logger`
|
860
|
+
* `active_record.logger` Sets `ActiveRecord::Base.logger` - if it's not already set - to `Rails.logger`.
|
676
861
|
|
677
862
|
* `active_record.set_configs` Sets up Active Record by using the settings in `config.active_record` by `send`'ing the method names as setters to `ActiveRecord::Base` and passing the values through.
|
678
863
|
|
@@ -682,7 +867,7 @@ Below is a comprehensive list of all the initializers found in Rails in the orde
|
|
682
867
|
|
683
868
|
* `active_record.set_dispatch_hooks` Resets all reloadable connections to the database if `config.cache_classes` is set to `false`.
|
684
869
|
|
685
|
-
* `action_mailer.logger` Sets `ActionMailer::Base.logger`
|
870
|
+
* `action_mailer.logger` Sets `ActionMailer::Base.logger` - if it's not already set - to `Rails.logger`.
|
686
871
|
|
687
872
|
* `action_mailer.set_configs` Sets up Action Mailer by using the settings in `config.action_mailer` by `send`'ing the method names as setters to `ActionMailer::Base` and passing the values through.
|
688
873
|
|
@@ -712,7 +897,7 @@ Below is a comprehensive list of all the initializers found in Rails in the orde
|
|
712
897
|
|
713
898
|
* `ensure_autoload_once_paths_as_subset` Ensures that the `config.autoload_once_paths` only contains paths from `config.autoload_paths`. If it contains extra paths, then an exception will be raised.
|
714
899
|
|
715
|
-
* `add_to_prepare_blocks` The block for every `config.to_prepare` call in the application, a railtie or engine is added to the `to_prepare` callbacks for Action Dispatch which will be
|
900
|
+
* `add_to_prepare_blocks` The block for every `config.to_prepare` call in the application, a railtie or engine is added to the `to_prepare` callbacks for Action Dispatch which will be run per request in development, or before the first request in production.
|
716
901
|
|
717
902
|
* `add_builtin_route` If the application is running under the development environment then this will append the route for `rails/info/properties` to the application routes. This route provides the detailed information such as Rails and Ruby version for `public/index.html` in a default Rails application.
|
718
903
|
|
@@ -743,4 +928,15 @@ Since the connection pooling is handled inside of Active Record by default, all
|
|
743
928
|
|
744
929
|
Any one request will check out a connection the first time it requires access to the database, after which it will check the connection back in, at the end of the request, meaning that the additional connection slot will be available again for the next request in the queue.
|
745
930
|
|
746
|
-
|
931
|
+
If you try to use more connections than are available, Active Record will block
|
932
|
+
and wait for a connection from the pool. When it cannot get connection, a timeout
|
933
|
+
error similar to given below will be thrown.
|
934
|
+
|
935
|
+
```ruby
|
936
|
+
ActiveRecord::ConnectionTimeoutError - could not obtain a database connection within 5 seconds. The max pool size is currently 5; consider increasing it:
|
937
|
+
```
|
938
|
+
|
939
|
+
If you get the above error, you might want to increase the size of connection
|
940
|
+
pool by incrementing the `pool` option in `database.yml`
|
941
|
+
|
942
|
+
NOTE. As Rails is multi-threaded by default, there could be a chance that several threads may be accessing multiple connections simultaneously. So depending on your current request load, you could very well have multiple threads contending for a limited amount of connections.
|
@@ -11,7 +11,7 @@ After reading this guide, you will know:
|
|
11
11
|
* How to contribute to the Ruby on Rails documentation.
|
12
12
|
* How to contribute to the Ruby on Rails code.
|
13
13
|
|
14
|
-
Ruby on Rails is not "someone else's framework." Over the years, hundreds of people have contributed to Ruby on Rails ranging from a single character to massive architectural changes or significant documentation
|
14
|
+
Ruby on Rails is not "someone else's framework." Over the years, hundreds of people have contributed to Ruby on Rails ranging from a single character to massive architectural changes or significant documentation - all with the goal of making Ruby on Rails better for everyone. Even if you don't feel up to writing code or documentation yet, there are a variety of other ways that you can contribute, from reporting issues to testing patches.
|
15
15
|
|
16
16
|
--------------------------------------------------------------------------------
|
17
17
|
|
@@ -26,7 +26,7 @@ NOTE: Bugs in the most recent released version of Ruby on Rails are likely to ge
|
|
26
26
|
|
27
27
|
If you've found a problem in Ruby on Rails which is not a security risk, do a search in GitHub under [Issues](https://github.com/rails/rails/issues) in case it was already reported. If you find no issue addressing it you can [add a new one](https://github.com/rails/rails/issues/new). (See the next section for reporting security issues.)
|
28
28
|
|
29
|
-
At the minimum, your issue report needs a title and descriptive text. But that's only a minimum. You should include as much relevant information as possible. You need at least to post the code sample that has the issue. Even better is to include a unit test that shows how the expected behavior is not occurring. Your goal should be to make it easy for yourself
|
29
|
+
At the minimum, your issue report needs a title and descriptive text. But that's only a minimum. You should include as much relevant information as possible. You need at least to post the code sample that has the issue. Even better is to include a unit test that shows how the expected behavior is not occurring. Your goal should be to make it easy for yourself - and others - to replicate the bug and figure out a fix.
|
30
30
|
|
31
31
|
Then, don't get your hopes up! Unless you have a "Code Red, Mission Critical, the World is Coming to an End" kind of bug, you're creating this issue report in the hope that others with the same problem will be able to collaborate with you on solving it. Do not expect that the issue report will automatically see any activity or that others will jump to fix it. Creating an issue like this is mostly to help yourself start on the path of fixing the problem and for others to confirm it with an "I'm having this problem too" comment.
|
32
32
|
|
@@ -55,7 +55,7 @@ can expect it to be marked "invalid" as soon as it's reviewed.
|
|
55
55
|
|
56
56
|
Sometimes, the line between 'bug' and 'feature' is a hard one to draw.
|
57
57
|
Generally, a feature is anything that adds new behavior, while a bug is
|
58
|
-
anything that fixes already existing behavior that is
|
58
|
+
anything that fixes already existing behavior that is misbehaving. Sometimes,
|
59
59
|
the core team will have to make a judgement call. That said, the distinction
|
60
60
|
generally just affects which release your patch will get in to; we love feature
|
61
61
|
submissions! They just won't get backported to maintenance branches.
|
@@ -136,7 +136,7 @@ You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` als
|
|
136
136
|
|
137
137
|
The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings.
|
138
138
|
|
139
|
-
|
139
|
+
If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag:
|
140
140
|
|
141
141
|
```bash
|
142
142
|
$ RUBYOPT=-W0 bundle exec rake test
|
@@ -193,7 +193,7 @@ After applying their branch, test it out! Here are some things to think about:
|
|
193
193
|
Once you're happy that the pull request contains a good change, comment on the GitHub issue indicating your approval. Your comment should indicate that you like the change and what you like about it. Something like:
|
194
194
|
|
195
195
|
<blockquote>
|
196
|
-
I like the way you've restructured that code in generate_finder_sql
|
196
|
+
I like the way you've restructured that code in generate_finder_sql - much nicer. The tests look good too.
|
197
197
|
</blockquote>
|
198
198
|
|
199
199
|
If your comment simply says "+1", then odds are that other reviewers aren't going to take it too seriously. Show that you took the time to review the pull request.
|
@@ -201,7 +201,8 @@ If your comment simply says "+1", then odds are that other reviewers aren't goin
|
|
201
201
|
Contributing to the Rails Documentation
|
202
202
|
---------------------------------------
|
203
203
|
|
204
|
-
Ruby on Rails has two main sets of documentation: the guides help you
|
204
|
+
Ruby on Rails has two main sets of documentation: the guides, which help you
|
205
|
+
learn about Ruby on Rails, and the API, which serves as a reference.
|
205
206
|
|
206
207
|
You can help improve the Rails guides by making them more coherent, consistent or readable, adding missing information, correcting factual errors, fixing typos, or bringing it up to date with the latest edge Rails. To get involved in the translation of Rails guides, please see [Translating Rails Guides](https://wiki.github.com/rails/docrails/translating-rails-guides).
|
207
208
|
|
@@ -219,7 +220,7 @@ When working with documentation, please take into account the [API Documentation
|
|
219
220
|
|
220
221
|
NOTE: As explained earlier, ordinary code patches should have proper documentation coverage. Docrails is only used for isolated documentation improvements.
|
221
222
|
|
222
|
-
NOTE: To help our CI servers you
|
223
|
+
NOTE: To help our CI servers you should add [ci skip] to your documentation commit message to skip build on that commit. Please remember to use it for commits containing only documentation changes.
|
223
224
|
|
224
225
|
WARNING: Docrails has a very strict policy: no code can be touched whatsoever, no matter how trivial or small the change. Only RDoc and guides can be edited via docrails. Also, CHANGELOGs should never be edited in docrails.
|
225
226
|
|
@@ -241,11 +242,11 @@ $ cd rails
|
|
241
242
|
$ git checkout -b my_new_branch
|
242
243
|
```
|
243
244
|
|
244
|
-
It doesn
|
245
|
+
It doesn't matter much what name you use, because this branch will only exist on your local computer and your personal repository on GitHub. It won't be part of the Rails Git repository.
|
245
246
|
|
246
247
|
### Write Your Code
|
247
248
|
|
248
|
-
Now get busy and add or edit code. You
|
249
|
+
Now get busy and add or edit code. You're on your branch now, so you can write whatever you want (you can check to make sure you're on the right branch with `git branch -a`). But if you're planning to submit your change back for inclusion in Rails, keep a few things in mind:
|
249
250
|
|
250
251
|
* Get the code right.
|
251
252
|
* Use Rails idioms and helpers.
|
@@ -258,10 +259,10 @@ more if the source code is mounted in `/vagrant` as happens in the recommended
|
|
258
259
|
workflow with the [rails-dev-box](https://github.com/rails/rails-dev-box).
|
259
260
|
|
260
261
|
As a compromise, test what your code obviously affects, and if the change is
|
261
|
-
not in railties run the whole test suite of the affected component. If all
|
262
|
-
|
263
|
-
as a safety net for catching
|
264
|
-
elsewhere.
|
262
|
+
not in railties, run the whole test suite of the affected component. If all
|
263
|
+
tests are passing, that's enough to propose your contribution. We have
|
264
|
+
[Travis CI](https://travis-ci.org/rails/rails) as a safety net for catching
|
265
|
+
unexpected breakages elsewhere.
|
265
266
|
|
266
267
|
TIP: Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability of Rails will generally not be accepted.
|
267
268
|
|
@@ -281,7 +282,7 @@ Rails follows a simple set of coding style conventions:
|
|
281
282
|
* Prefer `method { do_stuff }` instead of `method{do_stuff}` for single-line blocks.
|
282
283
|
* Follow the conventions in the source you see used already.
|
283
284
|
|
284
|
-
The above are guidelines
|
285
|
+
The above are guidelines - please use your best judgment in using them.
|
285
286
|
|
286
287
|
### Updating the CHANGELOG
|
287
288
|
|
@@ -289,7 +290,7 @@ The CHANGELOG is an important part of every release. It keeps the list of change
|
|
289
290
|
|
290
291
|
You should add an entry to the CHANGELOG of the framework that you modified if you're adding or removing a feature, committing a bug fix or adding deprecation notices. Refactorings and documentation changes generally should not go to the CHANGELOG.
|
291
292
|
|
292
|
-
A CHANGELOG entry should summarize what was changed and should end with author's name. You can use multiple lines if you need more space and you can attach code examples indented with 4 spaces. If a change is related to a specific issue, you should attach issue's number. Here is an example CHANGELOG entry:
|
293
|
+
A CHANGELOG entry should summarize what was changed and should end with author's name and it should go on top of a CHANGELOG. You can use multiple lines if you need more space and you can attach code examples indented with 4 spaces. If a change is related to a specific issue, you should attach issue's number. Here is an example CHANGELOG entry:
|
293
294
|
|
294
295
|
```
|
295
296
|
* Summary of a change that briefly describes what was changed. You can use multiple
|
@@ -360,7 +361,7 @@ TIP. Please squash your commits into a single commit when appropriate. This simp
|
|
360
361
|
|
361
362
|
### Update Your Branch
|
362
363
|
|
363
|
-
It
|
364
|
+
It's pretty likely that other changes to master have happened while you were working. Go get them:
|
364
365
|
|
365
366
|
```bash
|
366
367
|
$ git checkout master
|
@@ -466,7 +467,7 @@ the same way that you appreciate feedback on your patches.
|
|
466
467
|
|
467
468
|
### Iterate as Necessary
|
468
469
|
|
469
|
-
It
|
470
|
+
It's entirely possible that the feedback you get will suggest changes. Don't get discouraged: the whole point of contributing to an active open source project is to tap into community knowledge. If people are encouraging you to tweak your code, then it's worth making the tweaks and resubmitting. If the feedback is that your code doesn't belong in the core, you might still think about releasing it as a gem.
|
470
471
|
|
471
472
|
#### Squashing commits
|
472
473
|
|