kotovalexarian-likes-github
/
rails--rails
mirror of https://github.com/rails/rails.git
1
0
Fork 0
Code Releases Activity

Link config settings to the configuration guide [ci-skip] 

Since #43138, each config setting has its own linkable section in the
configuration guide.

This commit links config settings throughout the guides to their
sections in the configuration guide.
This commit is contained in:
Jonathan Hefner 2022-02-11 16:20:24 -06:00
parent 73e0a9c749
commit c7303ccc31
21 changed files with 144 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
guides/source/action_cable_overview.md
View File

@ -770,9 +770,10 @@ in the development environment.
### Consumer Configuration
To configure the URL, add a call to [`action_cable_meta_tag`][] in your HTML layout
HEAD. This uses a URL or path typically set via `config.action_cable.url` in the
HEAD. This uses a URL or path typically set via [`config.action_cable.url`][] in the
environment configuration files.
[`config.action_cable.url`]: configuring.html#config-action-cable-url
[`action_cable_meta_tag`]: https://api.rubyonrails.org/classes/ActionCable/Helpers/ActionCableHelper.html#method-i-action_cable_meta_tag
### Worker Pool Configuration
@ -823,7 +824,7 @@ For a full list of all configuration options, see the
Action Cable can run alongside your Rails application. For example, to
listen for WebSocket requests on `/websocket`, specify that path to
`config.action_cable.mount_path`:
[`config.action_cable.mount_path`][]:
```ruby
# config/application.rb
@ -840,6 +841,8 @@ For every instance of your server you create, and for every worker your server
spawns, you will also have a new instance of Action Cable, but the Redis or
PostgreSQL adapter keeps messages synced across connections.
[`config.action_cable.mount_path`]: configuring.html#config-action-cable-mount-path
### Standalone
The cable servers can be separated from your normal application server. It's

7
guides/source/action_controller_overview.md
View File

@ -1167,7 +1167,7 @@ Rails keeps a log file for each environment in the `log` folder. These are extre
### Parameters Filtering
You can filter out sensitive request parameters from your log files by
appending them to `config.filter_parameters` in the application configuration.
appending them to [`config.filter_parameters`][] in the application configuration.
These parameters will be marked [FILTERED] in the log.
```ruby
@ -1180,6 +1180,8 @@ expression. Rails adds a list of default filters, including `:passw`,
(`initializers/filter_parameter_logging.rb`) to handle typical application
parameters like `password`, `password_confirmation` and `my_token`.
[`config.filter_parameters`]: configuring.html#config-filter-parameters
### Redirects Filtering
Sometimes it's desirable to filter out from log files some sensitive locations your application is redirecting to.
@ -1272,6 +1274,7 @@ Force HTTPS protocol
If you'd like to ensure that communication to your controller is only possible
via HTTPS, you should do so by enabling the [`ActionDispatch::SSL`][] middleware via
`config.force_ssl` in your environment configuration.
[`config.force_ssl`][] in your environment configuration.
[`config.force_ssl`]: configuring.html#config-force-ssl
[`ActionDispatch::SSL`]: https://api.rubyonrails.org/classes/ActionDispatch/SSL.html

4
guides/source/action_mailbox_basics.md
View File

@ -333,11 +333,13 @@ on your side of the application. The InboundEmail simply stays in the system
for the extra time to provide debugging and forensics options.
The actual incineration is done via the `IncinerationJob` that's scheduled
to run after `config.action_mailbox.incinerate_after` time. This value is
to run after [`config.action_mailbox.incinerate_after`][] time. This value is
by default set to `30.days`, but you can change it in your production.rb
configuration. (Note that this far-future incineration scheduling relies on
your job queue being able to hold jobs for that long.)
[`config.action_mailbox.incinerate_after`]: configuring.html#config-action-mailbox-incinerate-after
## Working with Action Mailbox in development
It's helpful to be able to test incoming emails in development without actually

5
guides/source/action_mailer_basics.md
View File

@ -815,7 +815,7 @@ files (environment.rb, production.rb, etc...)
|`smtp_settings`|Allows detailed configuration for `:smtp` delivery method:<ul><li>`:address` - Allows you to use a remote mail server. Just change it from its default `"localhost"` setting.</li><li>`:port` - On the off chance that your mail server doesn't run on port 25, you can change it.</li><li>`:domain` - If you need to specify a HELO domain, you can do it here.</li><li>`:user_name` - If your mail server requires authentication, set the username in this setting.</li><li>`:password` - If your mail server requires authentication, set the password in this setting.</li><li>`:authentication` - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of `:plain` (will send the password in the clear), `:login` (will send password Base64 encoded) or `:cram_md5` (combines a Challenge/Response mechanism to exchange information and a cryptographic Message Digest 5 algorithm to hash important information)</li><li>`:enable_starttls` - Use STARTTLS when connecting to your SMTP server and fail if unsupported. Defaults to `false`.</li><li>`:enable_starttls_auto` - Detects if STARTTLS is enabled in your SMTP server and starts to use it. Defaults to `true`.</li><li>`:openssl_verify_mode` - When using TLS, you can set how OpenSSL checks the certificate. This is really useful if you need to validate a self-signed and/or a wildcard certificate. You can use the name of an OpenSSL verify constant ('none' or 'peer') or directly the constant (`OpenSSL::SSL::VERIFY_NONE` or `OpenSSL::SSL::VERIFY_PEER`).</li><li>`:ssl/:tls` - Enables the SMTP connection to use SMTP/TLS (SMTPS: SMTP over direct TLS connection)</li><li>`:open_timeout` - Number of seconds to wait while attempting to open a connection.</li><li>`:read_timeout` - Number of seconds to wait until timing-out a read(2) call.</li></ul>|
|`sendmail_settings`|Allows you to override options for the `:sendmail` delivery method.<ul><li>`:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`.</li><li>`:arguments` - The command line arguments to be passed to sendmail. Defaults to `-i`.</li></ul>|
|`raise_delivery_errors`|Whether or not errors should be raised if the email fails to be delivered. This only works if the external email server is configured for immediate delivery.|
|`delivery_method`|Defines a delivery method. Possible values are:<ul><li>`:smtp` (default), can be configured by using `config.action_mailer.smtp_settings`.</li><li>`:sendmail`, can be configured by using `config.action_mailer.sendmail_settings`.</li><li>`:file`: save emails to files; can be configured by using `config.action_mailer.file_settings`.</li><li>`:test`: save emails to `ActionMailer::Base.deliveries` array.</li></ul>See [API docs](https://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.|
|`delivery_method`|Defines a delivery method. Possible values are:<ul><li>`:smtp` (default), can be configured by using [`config.action_mailer.smtp_settings`][].</li><li>`:sendmail`, can be configured by using [`config.action_mailer.sendmail_settings`][].</li><li>`:file`: save emails to files; can be configured by using `config.action_mailer.file_settings`.</li><li>`:test`: save emails to `ActionMailer::Base.deliveries` array.</li></ul>See [API docs](https://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.|
|`perform_deliveries`|Determines whether deliveries are actually carried out when the `deliver` method is invoked on the Mail message. By default they are, but this can be turned off to help functional testing. If this value is `false`, `deliveries` array will not be populated even if `delivery_method` is `:test`.|
|`deliveries`|Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful for unit and functional testing.|
|`delivery_job`|The job class used with `deliver_later`. Defaults to `ActionMailer::MailDeliveryJob`.|
@ -826,6 +826,9 @@ For a complete writeup of possible configurations see the
[Configuring Action Mailer](configuring.html#configuring-action-mailer) in
our Configuring Rails Applications guide.
[`config.action_mailer.sendmail_settings`]: configuring.html#config-action-mailer-sendmail-settings
[`config.action_mailer.smtp_settings`]: configuring.html#config-action-mailer-smtp-settings
### Example Action Mailer Configuration
An example would be adding the following to your appropriate

4
guides/source/action_view_helpers.md
View File

@ -23,7 +23,7 @@ The following is only a brief overview summary of the helpers available in Actio
This module provides methods for generating HTML that links views to assets such as images, JavaScript files, stylesheets, and feeds.
By default, Rails links to these assets on the current host in the public folder, but you can direct Rails to link to assets from a dedicated assets server by setting `config.asset_host` in the application configuration, typically in `config/environments/production.rb`. For example, let's say your asset host is `assets.example.com`:
By default, Rails links to these assets on the current host in the public folder, but you can direct Rails to link to assets from a dedicated assets server by setting [`config.asset_host`][] in the application configuration, typically in `config/environments/production.rb`. For example, let's say your asset host is `assets.example.com`:
```ruby
config.asset_host = "assets.example.com"
@ -31,6 +31,8 @@ image_tag("rails.png")
# => <img src="http://assets.example.com/images/rails.png" />
```
[`config.asset_host`]: configuring.html#config-asset-host
#### auto_discovery_link_tag
Returns a link tag that browsers and feed readers can use to auto-detect an RSS, Atom, or JSON feed.

10
guides/source/active_job_basics.md
View File

@ -130,7 +130,7 @@ see the API Documentation for [`ActiveJob::QueueAdapters`][].
### Setting the Backend
You can easily set your queuing backend:
You can easily set your queuing backend with [`config.active_job.queue_adapter`]:
```ruby
# config/application.rb
@ -156,6 +156,8 @@ end
# was configured in `config.active_job.queue_adapter`.
```
[`config.active_job.queue_adapter`]: configuring.html#config-active-job-queue-adapter
### Starting the Backend
Since jobs run in parallel to your Rails application, most queuing libraries
@ -188,7 +190,7 @@ end
```
You can prefix the queue name for all your jobs using
`config.active_job.queue_name_prefix` in `application.rb`:
[`config.active_job.queue_name_prefix`][] in `application.rb`:
```ruby
# config/application.rb
@ -225,7 +227,7 @@ end
```
The default queue name prefix delimiter is '\_'. This can be changed by setting
`config.active_job.queue_name_delimiter` in `application.rb`:
[`config.active_job.queue_name_delimiter`][] in `application.rb`:
```ruby
# config/application.rb
@ -284,6 +286,8 @@ ProcessVideoJob.perform_later(Video.last)
NOTE: Make sure your queuing backend "listens" on your queue name. For some
backends you need to specify the queues to listen to.
[`config.active_job.queue_name_delimiter`]: configuring.html#config-active-job-queue-name-delimiter
[`config.active_job.queue_name_prefix`]: configuring.html#config-active-job-queue-name-prefix
[`queue_as`]: https://api.rubyonrails.org/classes/ActiveJob/QueueName/ClassMethods.html#method-i-queue_as
Callbacks

4
guides/source/active_record_migrations.md
View File

@ -1029,7 +1029,7 @@ summed up in the schema file.
### Types of Schema Dumps
The format of the schema dump generated by Rails is controlled by the
`config.active_record.schema_format` setting in `config/application.rb`. By
[`config.active_record.schema_format`][] setting in `config/application.rb`. By
default, the format is `:ruby`, but can also be set to `:sql`.
If `:ruby` is selected, then the schema is stored in `db/schema.rb`. If you look
@ -1074,6 +1074,8 @@ To load the schema from `db/structure.sql`, run `bin/rails db:schema:load`.
Loading this file is done by executing the SQL statements it contains. By
definition, this will create a perfect copy of the database's structure.
[`config.active_record.schema_format`]: configuring.html#config-active-record-schema-format
### Schema Dumps and Source Control
Because schema files are commonly used to create new databases, it is strongly

12
guides/source/active_record_multiple_databases.md
View File

@ -482,7 +482,7 @@ config.active_record.shard_resolver = ->(request) {
In Rails 6.1+, Active Record provides a new internal API for connection management.
In most cases applications will not need to make any changes except to opt-in to the
new behavior (if upgrading from 6.0 and below) by setting
`config.active_record.legacy_connection_handling = false`. If you have a single database
[`config.active_record.legacy_connection_handling`][] to `false`. If you have a single database
application, no other changes will be required. If you have a multiple database application
the following changes are required if your application is using these methods:
@ -500,11 +500,13 @@ you'll want writing or reading pools with `connection_handler.connection_pool_li
* If you turn off `legacy_connection_handling` in your application, any method that's unsupported
will raise an error (i.e. `connection_handlers=`).
[`config.active_record.legacy_connection_handling`]: configuring.html#config-active-record-legacy-connection-handling
## Granular Database Connection Switching
In Rails 6.1 it's possible to switch connections for one database instead of
all databases globally. To use this feature you must first set
`config.active_record.legacy_connection_handling` to `false` in your application
[`config.active_record.legacy_connection_handling`][] to `false` in your application
configuration. The majority of applications should not need to make any other
changes since the public APIs have the same behavior. See the above section for
how to enable and migrate away from `legacy_connection_handling`.
@ -546,7 +548,7 @@ connections globally.
### Handling associations with joins across databases
As of Rails 7.0+, Active Record has an option for handling associations that would perform
a join across multiple databases. If you have a has many through or a has one through association
a join across multiple databases. If you have a has many through or a has one through association
that you want to disable joining and perform 2 or more queries, pass the `disable_joins: true` option.
For example:
@ -570,8 +572,8 @@ class Yard
end
```
Previously calling `@dog.treats` without `disable_joins` or `@dog.yard` without `disable_joins`
would raise an error because databases are unable to handle joins across clusters. With the
Previously calling `@dog.treats` without `disable_joins` or `@dog.yard` without `disable_joins`
would raise an error because databases are unable to handle joins across clusters. With the
`disable_joins` option, Rails will generate multiple select queries
to avoid attempting joining across clusters. For the above association, `@dog.treats` would generate the
following SQL:

3
guides/source/active_record_querying.md
View File

@ -419,11 +419,12 @@ as long as they have no ordering, since the method needs to force an order
internally to iterate.
If an order is present in the receiver the behaviour depends on the flag
`config.active_record.error_on_ignored_order`. If true, `ArgumentError` is
[`config.active_record.error_on_ignored_order`][]. If true, `ArgumentError` is
raised, otherwise the order is ignored and a warning issued, which is the
default. This can be overridden with the option `:error_on_ignore`, explained
below.
[`config.active_record.error_on_ignored_order`]: configuring.html#config-active-record-error-on-ignored-order
[`find_each`]: https://api.rubyonrails.org/classes/ActiveRecord/Batches.html#method-i-find_each
##### Options for `find_each`

13
guides/source/active_storage_overview.md
View File

@ -821,7 +821,7 @@ The Active Storage variant tracker improves performance of this, by storing a
record in the database if the requested representation has been processed before.
Thus, the above code will only make an API call to the remote service (e.g. S3)
once, and once a variant is stored, will use that. The variant tracker runs
automatically, but can be disabled through `config.active_storage.track_variants`.
automatically, but can be disabled through [`config.active_storage.track_variants`][].
If you're rendering lots of images on a page, the above example could result
in N+1 queries loading all the variant records. To avoid these N+1 queries,
@ -833,6 +833,7 @@ message.images.with_all_variant_records.each do |file|
end
```
[`config.active_storage.track_variants`]: configuring.html#config-active-storage-track-variants
[`ActiveStorage::Representations::RedirectController`]: https://api.rubyonrails.org/classes/ActiveStorage/Representations/RedirectController.html
[`ActiveStorage::Attachment`]: https://api.rubyonrails.org/classes/ActiveStorage/Attachment.html
@ -852,16 +853,15 @@ location.
If a variant is requested, Active Storage will automatically apply
transformations depending on the image's format:
1. Content types that are variable (as dictated by `config.active_storage.variable_content_types`)
and not considered web images (as dictated by `config.active_storage.web_image_content_types`),
1. Content types that are variable (as dictated by [`config.active_storage.variable_content_types`][])
and not considered web images (as dictated by [`config.active_storage.web_image_content_types`][]),
will be converted to PNG.
2. If `quality` is not specified, the variant processor's default quality for the format will be used.
Active Storage can use either [Vips][] or MiniMagick as the variant processor.
The default depends on your `config.load_defaults` target version, and the
processor can be changed by setting [`config.active_storage.variant_processor`](
configuring.html#config-active-storage-variant-processor).
processor can be changed by setting [`config.active_storage.variant_processor`][].
The two processors are not fully compatible, so when migrating an existing application
between MiniMagick and Vips, some changes have to be made if using options that are format
@ -875,6 +875,9 @@ specific:
<%= image_tag user.avatar.variant(resize_to_limit: [100, 100], format: :jpeg, saver: { subsample_mode: "on", strip: true, interlace: true, quality: 80 }) %>
```
[`config.active_storage.variable_content_types`]: configuring.html#config-active-storage-variable-content-types
[`config.active_storage.variant_processor`]: configuring.html#config-active-storage-variant-processor
[`config.active_storage.web_image_content_types`]: configuring.html#config-active-storage-web-image-content-types
[`variant`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Representable.html#method-i-variant
[Vips]: https://www.rubydoc.info/gems/ruby-vips/Vips/Image

9
guides/source/active_support_core_extensions.md
View File

@ -85,7 +85,9 @@ That does not even put the entire Active Support in memory upfront indeed, some
### Active Support Within a Ruby on Rails Application
A Ruby on Rails application loads all Active Support unless `config.active_support.bare` is true. In that case, the application will only load what the framework itself cherry-picks for its own needs, and can still cherry-pick itself at any granularity level, as explained in the previous section.
A Ruby on Rails application loads all Active Support unless [`config.active_support.bare`][] is true. In that case, the application will only load what the framework itself cherry-picks for its own needs, and can still cherry-pick itself at any granularity level, as explained in the previous section.
[`config.active_support.bare`]: configuring.html#config-active-support-bare
Extensions to All Objects
-------------------------
@ -3214,7 +3216,7 @@ NOTE: Defined in `active_support/core_ext/date/calculations.rb`.
The methods [`beginning_of_week`][DateAndTime::Calculations#beginning_of_week] and [`end_of_week`][DateAndTime::Calculations#end_of_week] return the dates for the
beginning and end of the week, respectively. Weeks are assumed to start on
Monday, but that can be changed passing an argument, setting thread local
`Date.beginning_of_week` or `config.beginning_of_week`.
`Date.beginning_of_week` or [`config.beginning_of_week`][].
```ruby
d = Date.new(2010, 5, 8) # => Sat, 08 May 2010
@ -3228,6 +3230,7 @@ d.end_of_week(:sunday) # => Sat, 08 May 2010
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
[`config.beginning_of_week`]: configuring.html#config-beginning-of-week
[DateAndTime::Calculations#at_beginning_of_week]: https://api.rubyonrails.org/classes/DateAndTime/Calculations.html#method-i-at_beginning_of_week
[DateAndTime::Calculations#at_end_of_week]: https://api.rubyonrails.org/classes/DateAndTime/Calculations.html#method-i-at_end_of_week
[DateAndTime::Calculations#beginning_of_week]: https://api.rubyonrails.org/classes/DateAndTime/Calculations.html#method-i-beginning_of_week
@ -3257,7 +3260,7 @@ NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### `prev_week`, `next_week`
The method [`next_week`][DateAndTime::Calculations#next_week] receives a symbol with a day name in English (default is the thread local [`Date.beginning_of_week`][Date.beginning_of_week], or `config.beginning_of_week`, or `:monday`) and it returns the date corresponding to that day.
The method [`next_week`][DateAndTime::Calculations#next_week] receives a symbol with a day name in English (default is the thread local [`Date.beginning_of_week`][Date.beginning_of_week], or [`config.beginning_of_week`][], or `:monday`) and it returns the date corresponding to that day.
```ruby
d = Date.new(2010, 5, 9) # => Sun, 09 May 2010

8
guides/source/api_app.md
View File

@ -163,7 +163,7 @@ class definition:
config.api_only = true
```
In `config/environments/development.rb`, set `config.debug_exception_response_format`
In `config/environments/development.rb`, set [`config.debug_exception_response_format`][]
to configure the format used in responses when errors occur in development mode.
To render an HTML page with debugging information, use the value `:default`.
@ -194,6 +194,8 @@ class ApplicationController < ActionController::API
end
```
[`config.debug_exception_response_format`]: configuring.html#config-debug-exception-response-format
Choosing Middleware
--------------------
@ -285,7 +287,7 @@ If your front-end server supports accelerated file sending, `Rack::Sendfile`
will offload the actual file sending work to the front-end server.
You can configure the name of the header that your front-end server uses for
this purpose using `config.action_dispatch.x_sendfile_header` in the appropriate
this purpose using [`config.action_dispatch.x_sendfile_header`][] in the appropriate
environment's configuration file.
You can learn more about how to use `Rack::Sendfile` with popular
@ -306,6 +308,8 @@ config.action_dispatch.x_sendfile_header = "X-Accel-Redirect"
Make sure to configure your server to support these options following the
instructions in the `Rack::Sendfile` documentation.
[`config.action_dispatch.x_sendfile_header`]: configuring.html#config-action-dispatch-x-sendfile-header
### Using ActionDispatch::Request
`ActionDispatch::Request#params` will take parameters from the client in the JSON

34
guides/source/asset_pipeline.md
View File

@ -41,8 +41,8 @@ gem 'sassc-rails'
```
To set asset compression methods, set the appropriate configuration options
in `production.rb` - `config.assets.css_compressor` for your CSS and
`config.assets.js_compressor` for your JavaScript:
in `production.rb` - [`config.assets.css_compressor`][] for your CSS and
[`config.assets.js_compressor`][] for your JavaScript:
```ruby
config.assets.css_compressor = :yui
@ -52,6 +52,9 @@ config.assets.js_compressor = :terser
NOTE: The `sassc-rails` gem is automatically used for CSS compression if included
in the `Gemfile` and no `config.assets.css_compressor` option is set.
[`config.assets.css_compressor`]: configuring.html#config-assets-css-compressor
[`config.assets.js_compressor`]: configuring.html#config-assets-js-compressor
### Main Features
The first feature of the pipeline is to concatenate assets, which can reduce the
@ -134,13 +137,15 @@ that filenames are consistent based on their content.
Fingerprinting is enabled by default for both the development and production
environments. You can enable or disable it in your configuration through the
`config.assets.digest` option.
[`config.assets.digest`][] option.
More reading:
* [Optimize caching](https://developers.google.com/speed/docs/insights/LeverageBrowserCaching)
* [Revving Filenames: don't use querystring](http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/)
[`config.assets.digest`]: configuring.html#config-assets-digest
How to Use the Asset Pipeline
-----------------------------
@ -152,13 +157,15 @@ directory. Files in this directory are served by the Sprockets middleware.
Assets can still be placed in the `public` hierarchy. Any assets under `public`
will be served as static files by the application or web server when
`config.public_file_server.enabled` is set to true. You should use `app/assets` for
[`config.public_file_server.enabled`][] is set to true. You should use `app/assets` for
files that must undergo some pre-processing before they are served.
In production, Rails precompiles these files to `public/assets` by default. The
precompiled copies are then served as static assets by the web server. The files
in `app/assets` are never served directly in production.
[`config.public_file_server.enabled`]: configuring.html#config-public-file-server-enabled
### Controller Specific Assets
When you generate a scaffold or a controller, Rails also generates a
@ -248,7 +255,7 @@ is referenced as:
```
You can view the search path by inspecting
`Rails.application.config.assets.paths` in the Rails console.
[`Rails.application.config.assets.paths`][`config.assets.paths`] in the Rails console.
Besides the standard `assets/*` paths, additional (fully qualified) paths can be
added to the pipeline in `config/initializers/assets.rb`. For example:
@ -265,6 +272,8 @@ It is important to note that files you want to reference outside a manifest must
be added to the precompile array or they will not be available in the production
environment.
[`config.assets.paths`]: configuring.html#config-assets-paths
#### Using Index Files
Sprockets uses files named `index` (with the relevant extensions) for a special
@ -319,7 +328,7 @@ Alternatively, a request for a file with an SHA256 hash such as
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`,
Sprockets will also look through the paths specified in [`config.assets.paths`][],
which includes the standard application paths and any paths added by Rails
engines.
@ -598,7 +607,7 @@ NOTE: with the Asset Pipeline the `:cache` and `:concat` options aren't used
anymore, delete these options from the `javascript_include_tag` and
`stylesheet_link_tag`.
The fingerprinting behavior is controlled by the `config.assets.digest`
The fingerprinting behavior is controlled by the [`config.assets.digest`][]
initialization option (which defaults to `true`).
NOTE: Under normal circumstances the default `config.assets.digest` option
@ -611,7 +620,7 @@ content changes.
Rails comes bundled with a command to compile the asset manifests and other
files in the pipeline.
Compiled assets are written to the location specified in `config.assets.prefix`.
Compiled assets are written to the location specified in [`config.assets.prefix`][].
By default, this is the `/assets` directory.
You can call this command on the server during deployment to create compiled
@ -683,6 +692,8 @@ NOTE: If there are missing precompiled files in production you will get a
`Sprockets::Helpers::RailsHelper::AssetPaths::AssetNotPrecompiledError`
exception indicating the name of the missing file(s).
[`config.assets.prefix`]: configuring.html#config-assets-prefix
#### Far-future Expires Header
Precompiled assets exist on the file system and are served directly by your web
@ -829,7 +840,7 @@ valid CDN provider at the time of this writing). Now that you have configured
your CDN server, you need to tell browsers to use your CDN to grab assets
instead of your Rails server directly. You can do this by configuring Rails to
set your CDN as the asset host instead of using a relative path. To set your
asset host in Rails, you need to set `config.asset_host` in
asset host in Rails, you need to set [`config.asset_host`][] in
`config/environments/production.rb`:
```ruby
@ -875,12 +886,15 @@ it for future use.
If you want to serve only some assets from your CDN, you can use custom `:host`
option your asset helper, which overwrites value set in
`config.action_controller.asset_host`.
[`config.action_controller.asset_host`][].
```erb
<%= asset_path 'image.png', host: 'mycdnsubdomain.fictional-cdn.com' %>
```
[`config.action_controller.asset_host`]: configuring.html#config-action-controller-asset-host
[`config.asset_host`]: configuring.html#config-asset-host
#### Customize CDN Caching Behavior
A CDN works by caching content. If the CDN has stale or bad content, then it is

4
guides/source/association_basics.md
View File

@ -821,7 +821,7 @@ standard names. However, Active Record will not automatically identify
bi-directional associations that contain the `:through` or `:foreign_key`
options. Custom scopes on the opposite association also prevent automatic
identification, as do custom scopes on the association itself unless
`config.active_record.automatic_scope_inversing` is set to true (the default for
[`config.active_record.automatic_scope_inversing`][] is set to true (the default for
new applications).
For example, consider the following model declarations:
@ -900,6 +900,8 @@ By including the `:inverse_of` option in the `has_many` association declaration,
Active Record will now recognize the bi-directional association and behave as in
the initial examples above.
[`config.active_record.automatic_scope_inversing`]: configuring.html#config-active-record-automatic-scope-inversing
Detailed Association Reference
------------------------------

10
guides/source/autoloading_and_reloading_constants.md
View File

@ -178,9 +178,9 @@ Rails automatically reloads classes and modules if application files in the auto
More precisely, if the web server is running and application files have been modified, Rails unloads all autoloaded constants managed by the `main` autoloader just before the next request is processed. That way, application classes or modules used during that request will be autoloaded again, thus picking up their current implementation in the file system.
Reloading can be enabled or disabled. The setting that controls this behavior is `config.cache_classes`, which is false by default in `development` mode (reloading enabled), and true by default in `production` mode (reloading disabled).
Reloading can be enabled or disabled. The setting that controls this behavior is [`config.cache_classes`][], which is false by default in `development` mode (reloading enabled), and true by default in `production` mode (reloading disabled).
Rails uses an evented file monitor to detect files changes by default. It can be configured instead to detect file changes by walking the autoload paths. This is controlled by the `config.file_watcher` setting.
Rails uses an evented file monitor to detect files changes by default. It can be configured instead to detect file changes by walking the autoload paths. This is controlled by the [`config.file_watcher`][] setting.
In a Rails console there is no file watcher active regardless of the value of `config.cache_classes`. This is because, normally, it would be confusing to have code reloaded in the middle of a console session. Similar to an individual request, you generally want a console session to be served by a consistent, non-changing set of application classes and modules.
@ -198,6 +198,9 @@ irb(main):003:0> User.object_id
As you can see, the class object stored in the `User` constant is different after reloading.
[`config.cache_classes`]: configuring.html#config-cache-classes
[`config.file_watcher`]: configuring.html#config-file-watcher
### Reloading and Stale Objects
It is very important to understand that Ruby does not have a way to truly reload classes and modules in memory, and have that reflected everywhere they are already used. Technically, "unloading" the `User` class means removing the `User` constant via `Object.send(:remove_const, "User")`.
@ -300,12 +303,13 @@ Eager Loading
In production-like environments it is generally better to load all the application code when the application boots. Eager loading puts everything in memory ready to serve requests right away, and it is also [CoW](https://en.wikipedia.org/wiki/Copy-on-write)-friendly.
Eager loading is controlled by the flag `config.eager_load`, which is enabled by default in `production` mode.
Eager loading is controlled by the flag [`config.eager_load`][], which is enabled by default in `production` mode.
The order in which files are eager-loaded is undefined.
If the `Zeitwerk` constant is defined, Rails invokes `Zeitwerk::Loader.eager_load_all` regardless of the application autoloading mode. That ensures dependencies managed by Zeitwerk are eager-loaded.
[`config.eager_load`]: configuring.html#config-eager-load
Single Table Inheritance
------------------------

4
guides/source/caching_with_rails.md
View File

@ -36,13 +36,15 @@ page and action caching you will need to add `actionpack-page_caching` and
By default, caching is only enabled in your production environment. You can play
around with caching locally by running `rails dev:cache`, or by setting
`config.action_controller.perform_caching` to `true` in `config/environments/development.rb`.
[`config.action_controller.perform_caching`][] to `true` in `config/environments/development.rb`.
NOTE: Changing the value of `config.action_controller.perform_caching` will
only have an effect on the caching provided by Action Controller.
For instance, it will not impact low-level caching, that we address
[below](#low-level-caching).
[`config.action_controller.perform_caching`]: configuring.html#config-action-controller-perform-caching
### Page Caching
Page caching is a Rails mechanism which allows the request for a generated page

4
guides/source/engines.md
View File

@ -1508,7 +1508,7 @@ Configuration hooks do not hook into any particular framework, but instead they
| ---------------------- | ---------------------------------------------------------------------------------- |
| `before_configuration` | First configurable block to run. Called before any initializers are run. |
| `before_initialize` | Second configurable block to run. Called before frameworks initialize. |
| `before_eager_load` | Third configurable block to run. Does not run if `config.eager_load` set to false. |
| `before_eager_load` | Third configurable block to run. Does not run if [`config.eager_load`][] set to false. |
| `after_initialize` | Last configurable block to run. Called after frameworks initialize. |
Configuration hooks can be called in the Engine class.
@ -1522,3 +1522,5 @@ module Blorgh
end
end
```
[`config.eager_load`]: configuring.html#config-eager-load

12
guides/source/rails_on_rack.md
View File

@ -137,7 +137,9 @@ The default middlewares shown here (and some others) are each summarized in the
### Configuring Middleware Stack
Rails provides a simple configuration interface `config.middleware` for adding, removing, and modifying the middlewares in the middleware stack via `application.rb` or the environment specific configuration file `environments/<environment>.rb`.
Rails provides a simple configuration interface [`config.middleware`][] for adding, removing, and modifying the middlewares in the middleware stack via `application.rb` or the environment specific configuration file `environments/<environment>.rb`.
[`config.middleware`]: configuring.html#config-middleware
#### Adding a Middleware
@ -225,11 +227,15 @@ Much of Action Controller's functionality is implemented as Middlewares. The fol
**`Rack::Sendfile`**
* Sets server specific X-Sendfile header. Configure this via `config.action_dispatch.x_sendfile_header` option.
* Sets server specific X-Sendfile header. Configure this via [`config.action_dispatch.x_sendfile_header`][] option.
[`config.action_dispatch.x_sendfile_header`]: configuring.html#config-action-dispatch-x-sendfile-header
**`ActionDispatch::Static`**
* Used to serve static files from the public directory. Disabled if `config.public_file_server.enabled` is `false`.
* Used to serve static files from the public directory. Disabled if [`config.public_file_server.enabled`][] is `false`.
[`config.public_file_server.enabled`]: configuring.html#config-public-file-server-enabled
**`Rack::Lock`**

8
guides/source/security.md
View File

@ -287,7 +287,7 @@ There are many other possibilities, like using a `<script>` tag to make a cross-
NOTE: We can't distinguish a `<script>` tag's origin—whether it's a tag on your own site or on some other malicious site—so we must block all `<script>` across the board, even if it's actually a safe same-origin script served from your own site. In these cases, explicitly skip CSRF protection on actions that serve JavaScript meant for a `<script>` tag.
To protect against all other forged requests, we introduce a _required security token_ that our site knows but other sites don't know. We include the security token in requests and verify it on the server. This is done automatically when `config.action_controller.default_protect_from_forgery` is set to `true`, which is the default for newly created Rails applications. You can also do it manually by adding the following to your application controller:
To protect against all other forged requests, we introduce a _required security token_ that our site knows but other sites don't know. We include the security token in requests and verify it on the server. This is done automatically when [`config.action_controller.default_protect_from_forgery`][] is set to `true`, which is the default for newly created Rails applications. You can also do it manually by adding the following to your application controller:
```ruby
protect_from_forgery with: :exception
@ -315,6 +315,8 @@ The above method can be placed in the `ApplicationController` and will be called
Note that _cross-site scripting (XSS) vulnerabilities bypass all CSRF protections_. XSS gives the attacker access to all elements on a page, so they can read the CSRF security token from a form or directly submit the form. Read [more about XSS](#cross-site-scripting-xss) later.
[`config.action_controller.default_protect_from_forgery`]: configuring.html#config-action-controller-default-protect-from-forgery
Redirection and Files
---------------------
@ -504,7 +506,7 @@ Note that this protects you only from automatic bots, targeted tailor-made bots
WARNING: _Tell Rails not to put passwords in the log files._
By default, Rails logs all requests being made to the web application. But log files can be a huge security issue, as they may contain login credentials, credit card numbers et cetera. When designing a web application security concept, you should also think about what will happen if an attacker got (full) access to the web server. Encrypting secrets and passwords in the database will be quite useless, if the log files list them in clear text. You can _filter certain request parameters from your log files_ by appending them to `config.filter_parameters` in the application configuration. These parameters will be marked [FILTERED] in the log.
By default, Rails logs all requests being made to the web application. But log files can be a huge security issue, as they may contain login credentials, credit card numbers et cetera. When designing a web application security concept, you should also think about what will happen if an attacker got (full) access to the web server. Encrypting secrets and passwords in the database will be quite useless, if the log files list them in clear text. You can _filter certain request parameters from your log files_ by appending them to [`config.filter_parameters`][] in the application configuration. These parameters will be marked [FILTERED] in the log.
```ruby
config.filter_parameters << :password
@ -516,6 +518,8 @@ expression. Rails adds a list of default filters, including `:passw`,
(`initializers/filter_parameter_logging.rb`) to handle typical application
parameters like `password`, `password_confirmation` and `my_token`.
[`config.filter_parameters`]: configuring.html#config-filter-parameters
### Regular Expressions
INFO: _A common pitfall in Ruby's regular expressions is to match the string's beginning and end by ^ and $, instead of \A and \z._

5
guides/source/testing.md
View File

@ -264,8 +264,7 @@ Notice the 'E' in the output. It denotes a test with error.
NOTE: The execution of each test method stops as soon as any error or an
assertion failure is encountered, and the test suite continues with the next
method. All test methods are executed in random order. The
[`config.active_support.test_order` option](configuring.html#configuring-active-support)
can be used to configure test order.
[`config.active_support.test_order`][] option can be used to configure test order.
When a test fails you are presented with the corresponding backtrace. By default
Rails filters that backtrace and will only print lines relevant to your
@ -290,6 +289,8 @@ end
This test should now pass.
[`config.active_support.test_order`]: configuring.html#config-active-support-test-order
### Available Assertions
By now you've caught a glimpse of some of the assertions that are available. Assertions are the worker bees of testing. They are the ones that actually perform the checks to ensure that things are going as planned.

43
guides/source/upgrading_ruby_on_rails.md
View File

@ -88,7 +88,7 @@ size of the `bootsnap` cache for the others.
### `ActiveStorage::BaseController` no longer includes the streaming concern
Application controllers that inherit from `ActiveStorage::BaseController` and use streaming to implement custom file serving logic must now explicitly include the `ActiveStorage::Streaming` module.
Application controllers that inherit from `ActiveStorage::BaseController` and use streaming to implement custom file serving logic must now explicitly include the `ActiveStorage::Streaming` module.
### New `ActiveSupport::MessageEncryptor` default serializer
@ -197,7 +197,9 @@ If your application uses Spring, it needs to be upgraded to at least version 3.0
undefined method `mechanism=' for ActiveSupport::Dependencies:Module
```
Also, make sure `config.cache_classes` is set to `false` in `config/environments/test.rb`.
Also, make sure [`config.cache_classes`][] is set to `false` in `config/environments/test.rb`.
[`config.cache_classes`]: configuring.html#config-cache-classes
### Sprockets is now an optional dependency
@ -252,7 +254,7 @@ If you still get this warning in the logs, please check the section about autolo
### Ability to configure `config.autoload_once_paths`
`config.autoload_once_paths` can be set in the body of the application class defined in `config/application.rb` or in the configuration for environments in `config/environments/*`.
[`config.autoload_once_paths`][] can be set in the body of the application class defined in `config/application.rb` or in the configuration for environments in `config/environments/*`.
Similarly, engines can configure that collection in the class body of the engine class or in the configuration for environments.
@ -260,6 +262,8 @@ After that, the collection is frozen, and you can autoload from those paths. In
If you configured this setting after the environments configuration has been processed and are getting `FrozenError`, please just move the code.
[`config.autoload_once_paths`]: configuring.html#config-autoload-once-paths
### `ActionDispatch::Request#content_type` now returned Content-Type header as it is.
Previously, `ActionDispatch::Request#content_type` returned value does NOT contain charset part.
@ -651,9 +655,12 @@ $ bin/rails webpacker:install
### Force SSL
The `force_ssl` method on controllers has been deprecated and will be removed in
Rails 6.1. You are encouraged to enable `config.force_ssl` to enforce HTTPS
Rails 6.1. You are encouraged to enable [`config.force_ssl`][] to enforce HTTPS
connections throughout your application. If you need to exempt certain endpoints
from redirection, you can use `config.ssl_options` to configure that behavior.
from redirection, you can use [`config.ssl_options`][] to configure that behavior.
[`config.force_ssl`]: configuring.html#config-force-ssl
[`config.ssl_options`]: configuring.html#config-ssl-options
### Purpose and expiry metadata is now embedded inside signed and encrypted cookies for increased security
@ -939,18 +946,14 @@ In addition to that, Bootsnap needs to disable the iseq cache due to a bug in th
#### `config.add_autoload_paths_to_load_path`
The new configuration point
```ruby
config.add_autoload_paths_to_load_path
```
is `true` by default for backwards compatibility, but allows you to opt-out from adding the autoload paths to `$LOAD_PATH`.
The new configuration point [`config.add_autoload_paths_to_load_path`][] is `true` by default for backwards compatibility, but allows you to opt-out from adding the autoload paths to `$LOAD_PATH`.
This makes sense in most applications, since you never should require a file in `app/models`, for example, and Zeitwerk only uses absolute file names internally.
By opting-out you optimize `$LOAD_PATH` lookups (less directories to check), and save Bootsnap work and memory consumption, since it does not need to build an index for these directories.
[`config.add_autoload_paths_to_load_path`]: configuring.html#config-add-autoload-paths-to-load-path
#### Thread-safety
In classic mode, constant autoloading is not thread-safe, though Rails has locks in place for example to make web requests thread-safe when autoloading is enabled, as it is common in the development environment.
@ -1036,7 +1039,9 @@ user.highlights.first.filename # => "funky.jpg"
user.highlights.second.filename # => "town.jpg"
```
Existing applications can opt in to this new behavior by setting `config.active_storage.replace_on_assign_to_many` to `true`. The old behavior will be deprecated in Rails 7.0 and removed in Rails 7.1.
Existing applications can opt in to this new behavior by setting [`config.active_storage.replace_on_assign_to_many`][] to `true`. The old behavior will be deprecated in Rails 7.0 and removed in Rails 7.1.
[`config.active_storage.replace_on_assign_to_many`]: configuring.html#config-active-storage-replace-on-assign-to-many
Upgrading from Rails 5.1 to Rails 5.2
-------------------------------------
@ -1425,13 +1430,15 @@ config.action_mailer.deliver_later_queue_name = :new_queue_name
#### Support Fragment Caching in Action Mailer Views
Set `config.action_mailer.perform_caching` in your config to determine whether your Action Mailer views
Set [`config.action_mailer.perform_caching`][] in your config to determine whether your Action Mailer views
should support caching.
```ruby
config.action_mailer.perform_caching = true
```
[`config.action_mailer.perform_caching`]: configuring.html#config-action-mailer-perform-caching
#### Configure the Output of `db:structure:dump`
If you're using `schema_search_path` or other PostgreSQL extensions, you can control how the schema is
@ -2402,7 +2409,7 @@ or `link_to_unless`).
Please note that if your application is dependent on loading certain pages in a `<frame>` or `<iframe>`, then you may need to explicitly set `X-Frame-Options` to `ALLOW-FROM ...` or `ALLOWALL`.
* In Rails 4.0, precompiling assets no longer automatically copies non-JS/CSS assets from `vendor/assets` and `lib/assets`. Rails application and engine developers should put these assets in `app/assets` or configure `config.assets.precompile`.
* In Rails 4.0, precompiling assets no longer automatically copies non-JS/CSS assets from `vendor/assets` and `lib/assets`. Rails application and engine developers should put these assets in `app/assets` or configure [`config.assets.precompile`][].
* In Rails 4.0, `ActionController::UnknownFormat` is raised when the action doesn't handle the request format. By default, the exception is handled by responding with 406 Not Acceptable, but you can override that now. In Rails 3, 406 Not Acceptable was always returned. No overrides.
@ -2419,6 +2426,8 @@ or `link_to_unless`).
* Rails 4.0 deprecated `ActionController::Response` in favor of `ActionDispatch::Response`.
* Rails 4.0 deprecated `ActionController::Routing` in favor of `ActionDispatch::Routing`.
[`config.assets.precompile`]: configuring.html#config-assets-precompile
### Active Support
Rails 4.0 removes the `j` alias for `ERB::Util#json_escape` since `j` is already used for `ActionView::Helpers::JavaScriptHelper#escape_javascript`.
@ -2438,12 +2447,14 @@ The order in which helpers from more than one directory are loaded has changed i
### sprockets-rails
* `assets:precompile:primary` and `assets:precompile:all` have been removed. Use `assets:precompile` instead.
* The `config.assets.compress` option should be changed to `config.assets.js_compressor` like so for instance:
* The `config.assets.compress` option should be changed to [`config.assets.js_compressor`][] like so for instance:
```ruby
config.assets.js_compressor = :uglifier
```
[`config.assets.js_compressor`]: configuring.html#config-assets-js-compressor
### sass-rails
* `asset-url` with two arguments is deprecated. For example: `asset-url("rails.png", image)` becomes `asset-url("rails.png")`.