diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/5_1_release_notes.md | 4 | ||||
| -rw-r--r-- | guides/source/6_0_release_notes.md | 474 | ||||
| -rw-r--r-- | guides/source/action_text_overview.md | 2 | ||||
| -rw-r--r-- | guides/source/active_record_migrations.md | 2 | ||||
| -rw-r--r-- | guides/source/active_record_validations.md | 12 | ||||
| -rw-r--r-- | guides/source/active_storage_overview.md | 26 | ||||
| -rw-r--r-- | guides/source/active_support_core_extensions.md | 12 | ||||
| -rw-r--r-- | guides/source/active_support_instrumentation.md | 11 | ||||
| -rw-r--r-- | guides/source/association_basics.md | 31 | ||||
| -rw-r--r-- | guides/source/command_line.md | 33 | ||||
| -rw-r--r-- | guides/source/configuring.md | 27 | ||||
| -rw-r--r-- | guides/source/contributing_to_ruby_on_rails.md | 2 | ||||
| -rw-r--r-- | guides/source/engines.md | 57 | ||||
| -rw-r--r-- | guides/source/getting_started.md | 10 | ||||
| -rw-r--r-- | guides/source/i18n.md | 21 | ||||
| -rw-r--r-- | guides/source/routing.md | 2 | ||||
| -rw-r--r-- | guides/source/testing.md | 4 | ||||
| -rw-r--r-- | guides/source/upgrading_ruby_on_rails.md | 277 |
18 files changed, 881 insertions, 126 deletions
diff --git a/guides/source/5_1_release_notes.md b/guides/source/5_1_release_notes.md index e885b1e42e..f870c4c47c 100644 --- a/guides/source/5_1_release_notes.md +++ b/guides/source/5_1_release_notes.md @@ -41,8 +41,8 @@ Major Features [Pull Request](https://github.com/rails/rails/pull/26836) Rails 5.1 allows managing JavaScript dependencies -from NPM via Yarn. This will make it easy to use libraries like React, VueJS -or any other library from NPM world. The Yarn support is integrated with +from npm via Yarn. This will make it easy to use libraries like React, VueJS +or any other library from npm world. The Yarn support is integrated with the asset pipeline so that all dependencies will work seamlessly with the Rails 5.1 app. diff --git a/guides/source/6_0_release_notes.md b/guides/source/6_0_release_notes.md index 180cfa371c..fa45e7240d 100644 --- a/guides/source/6_0_release_notes.md +++ b/guides/source/6_0_release_notes.md @@ -151,25 +151,44 @@ Please refer to the [Changelog][action-cable] for detailed changes. ### Removals +* Replace `ActionCable.startDebugging()` and `ActionCable.stopDebugging()` + with `ActionCable.logger.enabled`. + ([Pull Request](https://github.com/rails/rails/pull/34370)) + ### Deprecations +* There are no deprecations for Action Cable in Rails 6.0. + ### Notable changes -* The ActionCable javascript package has been converted from CoffeeScript - to ES2015, and we now publish the source code in the npm distribution. +* Add support for the `channel_prefix` option for PostgreSQL subscription adapters + in `cable.yml`. + ([Pull Request](https://github.com/rails/rails/pull/35276)) + +* Allow passing a custom configuration to `ActionCable::Server::Base`. + ([Pull Request](https://github.com/rails/rails/pull/34714)) + +* Add `:action_cable_connection` and `:action_cable_channel` load hooks. + ([Pull Request](https://github.com/rails/rails/pull/35094)) + +* Add `Channel::Base#broadcast_to` and `Channel::Base.broadcasting_for`. + ([Pull Request](https://github.com/rails/rails/pull/35021)) - This allows ActionCable users to depend on the javascript source code - rather than the compiled code, which can produce smaller javascript bundles. +* Close a connection when calling `reject_unauthorized_connection` from an + `ActionCable::Connection`. + ([Pull Request](https://github.com/rails/rails/pull/34194)) - This change includes some breaking changes to optional parts of the - ActionCable javascript API: +* Convert the Action Cable JavaScript package from CoffeeScript to ES2015 and + publish the source code in the npm distribution. + ([Pull Request](https://github.com/rails/rails/pull/34370)) - - Configuration of the WebSocket adapter and logger adapter have been moved - from properties of `ActionCable` to properties of `ActionCable.adapters`. +* Move the configuration of the WebSocket adapter and logger adapter + from properties of `ActionCable` to `ActionCable.adapters`. + ([Pull Request](https://github.com/rails/rails/pull/34370)) - - The `ActionCable.startDebugging()` and `ActionCable.stopDebugging()` - methods have been removed and replaced with the property - `ActionCable.logger.enabled`. +* Add an `id` option to the Redis adapter to distinguish Action Cable's Redis + connections. + ([Pull Request](https://github.com/rails/rails/pull/33798)) Action Pack ----------- @@ -178,10 +197,78 @@ Please refer to the [Changelog][action-pack] for detailed changes. ### Removals +* Remove deprecated `fragment_cache_key` helper in favor of `combined_fragment_cache_key`. + ([Commit](https://github.com/rails/rails/commit/e70d3df7c9b05c129b0fdcca57f66eca316c5cfc)) + +* Remove deprecated methods in `ActionDispatch::TestResponse`: + `#success?` in favor of `#successful?`, `#missing?` in favor of `#not_found?`, + `#error?` in favor of `#server_error?`. + ([Commit](https://github.com/rails/rails/commit/13ddc92e079e59a0b894e31bf5bb4fdecbd235d1)) + ### Deprecations +* Deprecate `ActionDispatch::Http::ParameterFilter` in favor of `ActiveSupport::ParameterFilter`. + ([Pull Request](https://github.com/rails/rails/pull/34039)) + +* Deprecate controller level `force_ssl` in favor of `config.force_ssl`. + ([Pull Request](https://github.com/rails/rails/pull/32277)) + ### Notable changes +* Raise an `ArgumentError` if a resource param contains a colon. + ([Pull Request](https://github.com/rails/rails/pull/35236)) + +* Allow `ActionDispatch::SystemTestCase.driven_by` to be called with a block + to define specific browser capabilities. + ([Pull Request](https://github.com/rails/rails/pull/35081)) + +* Add `ActionDispatch::HostAuthorization` middleware that guards against DNS rebinding + attacks. + ([Pull Request](https://github.com/rails/rails/pull/33145)) + +* Allow the use of `parsed_body` in `ActionController::TestCase`. + ([Pull Request](https://github.com/rails/rails/pull/34717)) + +* Raise an `ArgumentError` when multiple root routes exist in the same context + without `as:` naming specifications. + ([Pull Request](https://github.com/rails/rails/pull/34494)) + +* Allow the use of `#rescue_from` for handling parameter parsing errors. + ([Pull Request](https://github.com/rails/rails/pull/34341)) + +* Add `ActionController::Parameters#each_value` for iterating through parameters. + ([Pull Request](https://github.com/rails/rails/pull/33979)) + +* Encode Content-Disposition filenames on `send_data` and `send_file`. + ([Pull Request](https://github.com/rails/rails/pull/33829)) + +* Expose `ActionController::Parameters#each_key`. + ([Pull Request](https://github.com/rails/rails/pull/33758)) + +* Add purpose and expiry metadata inside signed/encrypted cookies to prevent copying the value of + cookies into one another. + ([Pull Request](https://github.com/rails/rails/pull/32937)) + +* Raise `ActionController::RespondToMismatchError` for conflicting `respond_to` invocations. + ([Pull Request](https://github.com/rails/rails/pull/33446)) + +* Add an explicit error page for when a template is missing for a request format. + ([Pull Request](https://github.com/rails/rails/pull/29286)) + +* Introduce `ActionDispatch::DebugExceptions.register_interceptor`, a way to hook into + DebugExceptions and process the exception, before being rendered. + ([Pull Request](https://github.com/rails/rails/pull/23868)) + +* Output only one Content-Security-Policy nonce header value per request. + ([Pull Request](https://github.com/rails/rails/pull/32602)) + +* Add a module specifically for the Rails default headers configuration + that can be explicitly included in controllers. + ([Pull Request](https://github.com/rails/rails/pull/32484)) + +* Add `#dig` to `ActionDispatch::Request::Session`. + ([Pull Request](https://github.com/rails/rails/pull/32446)) + Action View ----------- @@ -189,10 +276,63 @@ Please refer to the [Changelog][action-view] for detailed changes. ### Removals +* Remove deprecated `image_alt` helper. + ([Commit](https://github.com/rails/rails/commit/60c8a03c8d1e45e48fcb1055ba4c49ed3d5ff78f)) + +* Remove an empty `RecordTagHelper` module from which the functionality + was already moved to the `record_tag_helper` gem. + ([Commit](https://github.com/rails/rails/commit/5c5ddd69b1e06fb6b2bcbb021e9b8dae17e7cb31)) + ### Deprecations +* Deprecate `ActionView::Template.finalize_compiled_template_methods` with + no replacement. + ([Pull Request](https://github.com/rails/rails/pull/35036)) + +* Deprecate `config.action_view.finalize_compiled_template_methods` with + no replacement. + ([Pull Request](https://github.com/rails/rails/pull/35036)) + +* Deprecate calling private model methods from the `options_from_collection_for_select` view helper. + ([Pull Request](https://github.com/rails/rails/pull/33547)) + ### Notable changes +* Clear Action View cache in development only on file changes, speeding up + development mode. + ([Pull Request](https://github.com/rails/rails/pull/35629)) + +* Move all of the Rails npm packages into a `@rails` scope. + ([Pull Request](https://github.com/rails/rails/pull/34905)) + +* Only accept formats from registered MIME types. + ([Pull Request](https://github.com/rails/rails/pull/35604), [Pull Request](https://github.com/rails/rails/pull/35753)) + +* Add allocations to the template and partial rendering server output. + ([Pull Request](https://github.com/rails/rails/pull/34136)) + +* Add a `year_format` option to `date_select` tag, making it possible to + customize year names. + ([Pull Request](https://github.com/rails/rails/pull/32190)) + +* Add a `nonce: true` option for `javascript_include_tag` helper to + support automatic nonce generation for a Content Security Policy. + ([Pull Request](https://github.com/rails/rails/pull/32607)) + +* Add a `action_view.finalize_compiled_template_methods` configuration to disable or + enable `ActionView::Template` finalizers. + ([Pull Request](https://github.com/rails/rails/pull/32418)) + +* Extract the JavaScript `confirm` call to its own, overridable method in `rails_ujs`. + ([Pull Request](https://github.com/rails/rails/pull/32404)) + +* Add a `action_controller.default_enforce_utf8` configuration option to handle + enforcing UTF-8 encoding. This defaults to `false`. + ([Pull Request](https://github.com/rails/rails/pull/32125)) + +* Add I18n key style support for locale keys to submit tags. + ([Pull Request](https://github.com/rails/rails/pull/26799)) + Action Mailer ------------- @@ -202,8 +342,41 @@ Please refer to the [Changelog][action-mailer] for detailed changes. ### Deprecations +* Deprecate `ActionMailer::Base.receive` in favor of Action Mailbox. + ([Commit](https://github.com/rails/rails/commit/e3f832a7433a291a51c5df397dc3dd654c1858cb)) + +* Deprecate `DeliveryJob` and `Parameterized::DeliveryJob` in favor of + `MailDeliveryJob`. + ([Pull Request](https://github.com/rails/rails/pull/34591)) + ### Notable changes +* Add `MailDeliveryJob` for delivering both regular and parameterized mail. + ([Pull Request](https://github.com/rails/rails/pull/34591)) + +* Allow custom email delivery jobs to work with the Action Mailer test assertions. + ([Pull Request](https://github.com/rails/rails/pull/34339)) + +* Allow specifying a template name for multipart emails with blocks instead of + using just the action name. + ([Pull Request](https://github.com/rails/rails/pull/22534)) + +* Add `perform_deliveries` to payload of `deliver.action_mailer` notification. + ([Pull Request](https://github.com/rails/rails/pull/33824)) + +* Improve the logging message when `perform_deliveries` is false to indicate + that sending of emails was skipped. + ([Pull Request](https://github.com/rails/rails/pull/33824)) + +* Allow calling `assert_enqueued_email_with` without block. + ([Pull Request](https://github.com/rails/rails/pull/33258)) + +* Perform the enqueued mail delivery jobs in the `assert_emails` block. + ([Pull Request](https://github.com/rails/rails/pull/32231)) + +* Allow `ActionMailer::Base` to unregister observers and interceptors. + ([Pull Request](https://github.com/rails/rails/pull/32207)) + Active Record ------------- @@ -229,7 +402,7 @@ Please refer to the [Changelog][active-record] for detailed changes. * Remove support for passing the column name to `count` when a block is passed. ([Commit](https://github.com/rails/rails/commit/67356f2034ab41305af7218f7c8b2fee2d614129)) -* Remove support for delegation of missing methods in a relation to arel. +* Remove support for delegation of missing methods in a relation to Arel. ([Commit](https://github.com/rails/rails/commit/d97980a16d76ad190042b4d8578109714e9c53d0)) * Remove support for delegating missing methods in a relation to private methods of the class. @@ -272,7 +445,7 @@ Please refer to the [Changelog][active-record] for detailed changes. ### Notable changes -* Bump the minimum sqlite3 version to 1.4. +* Bump the minimum version of the `sqlite3` gem to 1.4. ([Pull Request](https://github.com/rails/rails/pull/35844)) * Add `rails db:prepare` to create a database if it doesn't exist, and run its migrations. @@ -294,7 +467,7 @@ Please refer to the [Changelog][active-record] for detailed changes. ([Pull Request](https://github.com/rails/rails/pull/35631)) * Add `rails db:seed:replant` that truncates tables of each database - for ther current environment and loads the seeds. + for the current environment and loads the seeds. ([Pull Request](https://github.com/rails/rails/pull/34779)) * Add `reselect` method, which is a short-hand for `unscope(:select).select(fields)`. @@ -404,7 +577,7 @@ Please refer to the [Changelog][active-record] for detailed changes. * Allow the `:to_table` option of `remove_foreign_key` to be invertible. ([Pull Request](https://github.com/rails/rails/pull/33530)) -* Fix default value for mysql time types with specified precision. +* Fix default value for MySQL time types with specified precision. ([Pull Request](https://github.com/rails/rails/pull/33280)) * Fix the `touch` option to behave consistently with `Persistence#touch` method. @@ -451,9 +624,68 @@ Please refer to the [Changelog][active-storage] for detailed changes. ### Deprecations +* Deprecate `config.active_storage.queue` in favor of `config.active_storage.queues.analysis` + and `config.active_storage.queues.purge`. + ([Pull Request](https://github.com/rails/rails/pull/34838)) + +* Deprecate `ActiveStorage::Downloading` in favor of `ActiveStorage::Blob#open`. + ([Commit](https://github.com/rails/rails/commit/ee21b7c2eb64def8f00887a9fafbd77b85f464f1)) + +* Deprecate using `mini_magick` directly for generating image variants in favor of + `image_processing`. + ([Commit](https://github.com/rails/rails/commit/697f4a93ad386f9fb7795f0ba68f815f16ebad0f)) + +* Deprecate `:combine_options` in Active Storage's ImageProcessing transformer + without replacement. + ([Commit](https://github.com/rails/rails/commit/697f4a93ad386f9fb7795f0ba68f815f16ebad0f)) + ### Notable changes -* Updating an attached model via `update` or `update!` ala `@user.update!(images: [ … ])` now replaces the existing images instead of merely adding to them. +* Add support for generating BMP image variants. + ([Pull Request](https://github.com/rails/rails/pull/36051)) + +* Add support for generating TIFF image variants. + ([Pull Request](https://github.com/rails/rails/pull/34824)) + +* Add support for generating progressive JPEG image variants. + ([Pull Request](https://github.com/rails/rails/pull/34455)) + +* Add `ActiveStorage.routes_prefix` for configuring the Active Storage generated routes. + ([Pull Request](https://github.com/rails/rails/pull/33883)) + +* Generate a 404 Not Found response on `ActiveStorage::DiskController#show` when + the requested file is missing from the disk service. + ([Pull Request](https://github.com/rails/rails/pull/33666)) + +* Raise `ActiveStorage::FileNotFoundError` when the requested file is missing for + `ActiveStorage::Blob#download` and `ActiveStorage::Blob#open`. + ([Pull Request](https://github.com/rails/rails/pull/33666)) + +* Add a generic `ActiveStorage::Error` class that Active Storage exceptions inherit from. + ([Commit](https://github.com/rails/rails/commit/18425b837149bc0d50f8d5349e1091a623762d6b)) + +* Persist uploaded files assigned to a record to storage when the record + is saved instead of immediately. + ([Pull Request](https://github.com/rails/rails/pull/33303)) + +* Add the ability to reflect on defined attachments using the existing + Active Record reflection mechanism. + ([Pull Request](https://github.com/rails/rails/pull/33018)) + +* Add `ActiveStorage::Blob#open`, which downloads a blob to a tempfile on disk + and yields the tempfile. + ([Commit](https://github.com/rails/rails/commit/ee21b7c2eb64def8f00887a9fafbd77b85f464f1)) + +* Support streaming downloads from Google Cloud Storage. Require version 1.11+ + of the `google-cloud-storage` gem. + ([Pull Request](https://github.com/rails/rails/pull/32788)) + +* Use the `image_processing` gem for Active Storage variants. This replaces using + `mini_magick` directly. + ([Pull Request](https://github.com/rails/rails/pull/32471) + +* Replace existing images instead of adding to them when updating an + attached model via `update` or `update!` with, say, `@user.update!(images: [ … ])`. ([Pull Request](https://github.com/rails/rails/pull/33303)) Active Model @@ -479,6 +711,30 @@ Please refer to the [Changelog][active-model] for detailed changes. * Add `ActiveModel::Errors#of_kind?` to check presence of a specific error. ([Pull Request](https://github.com/rails/rails/pull/34866)) +* Fix `ActiveModel::Serializers::JSON#as_json` method for timestamps. + ([Pull Request](https://github.com/rails/rails/pull/31503)) + +* Fix numericality validator to still use value before type cast except Active Record. + ([Pull Request](https://github.com/rails/rails/pull/33654)) + +* Fix numericality equality validation of `BigDecimal` and `Float` + by casting to `BigDecimal` on both ends of the validation. + ([Pull Request](https://github.com/rails/rails/pull/32852)) + +* Fix year value when casting a multiparameter time hash. + ([Pull Request](https://github.com/rails/rails/pull/34990)) + +* Type cast falsy boolean symbols on boolean attribute as false. + ([Pull Request](https://github.com/rails/rails/pull/35794)) + +* Return correct date while converting parameters in `value_from_multiparameter_assignment` + for `ActiveModel::Type::Date`. + ([Pull Request](https://github.com/rails/rails/pull/29651)) + +* Fall back to parent locale before falling back to the `:errors` namespace while fetching + error translations. + ([Pull Request](https://github.com/rails/rails/pull/35424)) + Active Support -------------- @@ -486,10 +742,196 @@ Please refer to the [Changelog][active-support] for detailed changes. ### Removals +* Remove deprecated `#acronym_regex` method from `Inflections`. + ([Commit](https://github.com/rails/rails/commit/0ce67d3cd6d1b7b9576b07fecae3dd5b422a5689)) + +* Remove deprecated `Module#reachable?` method. + ([Commit](https://github.com/rails/rails/commit/6eb1d56a333fd2015610d31793ed6281acd66551)) + +* Remove `` Kernel#` `` without any replacement. + ([Pull Request](https://github.com/rails/rails/pull/31253)) + ### Deprecations +* Deprecate using negative integer arguments for `String#first` and + `String#last`. + ([Pull Request](https://github.com/rails/rails/pull/33058)) + +* Deprecate `ActiveSupport::Multibyte::Unicode#downcase/upcase/swapcase` + in favor of `String#downcase/upcase/swapcase`. + ([Pull Request](https://github.com/rails/rails/pull/34123)) + +* Deprecate `ActiveSupport::Multibyte::Unicode#normalize` + and `ActiveSupport::Multibyte::Chars#normalize` in favor of + `String#unicode_normalize`. + ([Pull Request](https://github.com/rails/rails/pull/34202)) + +* Deprecate `ActiveSupport::Multibyte::Chars.consumes?` in favor of + `String#is_utf8?`. + ([Pull Request](https://github.com/rails/rails/pull/34215)) + +* Deprecate `ActiveSupport::Multibyte::Unicode#pack_graphemes(array)` + and `ActiveSupport::Multibyte::Unicode#unpack_graphemes(string)` + in favor of `array.flatten.pack("U*")` and `string.scan(/\X/).map(&:codepoints)`, + respectively. + ([Pull Request](https://github.com/rails/rails/pull/34254)) + ### Notable changes +* Add support for parallel testing. + ([Pull Request](https://github.com/rails/rails/pull/31900)) + +* Make sure that `String#strip_heredoc` preserves frozen-ness of strings. + ([Pull Request](https://github.com/rails/rails/pull/32037)) + +* Add `String#truncate_bytes` to truncate a string to a maximum bytesize + without breaking multibyte characters or grapheme clusters. + ([Pull Request](https://github.com/rails/rails/pull/27319)) + +* Add `private` option to `delegate` method in order to delegate to + private methods. This option accepts `true/false` as the value. + ([Pull Request](https://github.com/rails/rails/pull/31944)) + +* Add support for translations through I18n for `ActiveSupport::Inflector#ordinal` + and `ActiveSupport::Inflector#ordinalize`. + ([Pull Request](https://github.com/rails/rails/pull/32168)) + +* Add `before?` and `after?` methods to `Date`, `DateTime`, + `Time`, and `TimeWithZone`. + ([Pull Request](https://github.com/rails/rails/pull/32185)) + +* Fix bug where `URI.unescape` would fail with mixed Unicode/escaped character + input. + ([Pull Request](https://github.com/rails/rails/pull/32183)) + +* Fix bug where `ActiveSupport::Cache` would massively inflate the storage + size when compression was enabled. + ([Pull Request](https://github.com/rails/rails/pull/32539)) + +* Redis cache store: `delete_matched` no longer blocks the Redis server. + ([Pull Request](https://github.com/rails/rails/pull/32614)) + +* Fix bug where `ActiveSupport::TimeZone.all` would fail when tzinfo data for + any timezone defined in `ActiveSupport::TimeZone::MAPPING` was missing. + ([Pull Request](https://github.com/rails/rails/pull/32613)) + +* Add `Enumerable#index_with` which allows creating a hash from an enumerable + with the value from a passed block or a default argument. + ([Pull Request](https://github.com/rails/rails/pull/32523)) + +* Allow `Range#===` and `Range#cover?` methods to work with `Range` argument. + ([Pull Request](https://github.com/rails/rails/pull/32938)) + +* Support key expiry in `increment/decrement` operations of RedisCacheStore. + ([Pull Request](https://github.com/rails/rails/pull/33254)) + +* Add cpu time, idle time, and allocations features to log subscriber events. + ([Pull Request](https://github.com/rails/rails/pull/33449)) + +* Add support for event object to the Active Support notification system. + ([Pull Request](https://github.com/rails/rails/pull/33451)) + +* Add support for not caching `nil` entries by introducing new option `skip_nil` + for `ActiveSupport::Cache#fetch`. + ([Pull Request](https://github.com/rails/rails/pull/25437)) + +* Add `Array#extract!` method which removes and returns the elements for which + block returns a true value. + ([Pull Request](https://github.com/rails/rails/pull/33137)) + +* Keep an HTML-safe string HTML-safe after slicing. + ([Pull Request](https://github.com/rails/rails/pull/33808)) + +* Add support for tracing constant autoloads via logging. + ([Commit](https://github.com/rails/rails/commit/c03bba4f1f03bad7dc034af555b7f2b329cf76f5)) + +* Define `unfreeze_time` as an alias of `travel_back`. + ([Pull Request](https://github.com/rails/rails/pull/33813)) + +* Change `ActiveSupport::TaggedLogging.new` to return a new logger instance + instead of mutating the one received as argument. + ([Pull Request](https://github.com/rails/rails/pull/27792)) + +* Treat `#delete_prefix`, `#delete_suffix` and `#unicode_normalize` methods + as non HTML-safe methods. + ([Pull Request](https://github.com/rails/rails/pull/33990)) + +* Fix bug where `#without` for `ActiveSupport::HashWithIndifferentAccess` + would fail with symbol arguments. + ([Pull Request](https://github.com/rails/rails/pull/34012)) + +* Rename `Module#parent`, `Module#parents`, and `Module#parent_name` to + `module_parent`, `module_parents`, and `module_parent_name`. + ([Pull Request](https://github.com/rails/rails/pull/34051)) + +* Add `ActiveSupport::ParameterFilter`. + ([Pull Request](https://github.com/rails/rails/pull/34039)) + +* Fix issue where duration was being rounded to a full second when a float + was added to the duration. + ([Pull Request](https://github.com/rails/rails/pull/34135)) + +* Make `#to_options` an alias for `#symbolize_keys` in + `ActiveSupport::HashWithIndifferentAccess`. + ([Pull Request](https://github.com/rails/rails/pull/34360)) + +* Don't raise an exception anymore if the same block is included multiple times + for a Concern. + ([Pull Request](https://github.com/rails/rails/pull/34553)) + +* Preserve key order passed to `ActiveSupport::CacheStore#fetch_multi`. + ([Pull Request](https://github.com/rails/rails/pull/34700)) + +* Fix `String#safe_constantize` to not throw a `LoadError` for incorrectly + cased constant references. + ([Pull Request](https://github.com/rails/rails/pull/34892)) + +* Add `Hash#deep_transform_values` and `Hash#deep_transform_values!`. + ([Commit](https://github.com/rails/rails/commit/b8dc06b8fdc16874160f61dcf58743fcc10e57db)) + +* Add `ActiveSupport::HashWithIndifferentAccess#assoc`. + ([Pull Request](https://github.com/rails/rails/pull/35080)) + +* Add `before_reset` callback to `CurrentAttributes` and define + `after_reset` as an alias of `resets` for symmetry. + ([Pull Request](https://github.com/rails/rails/pull/35063)) + +* Revise `ActiveSupport::Notifications.unsubscribe` to correctly + handle Regex or other multiple-pattern subscribers. + ([Pull Request](https://github.com/rails/rails/pull/32861)) + +* Add new autoloading mechanism using Zeitwerk. + ([Commit](https://github.com/rails/rails/commit/e53430fa9af239e21e11548499d814f540d421e5)) + +* Add `Array#including` and `Enumerable#including` to conveniently enlarge + a collection. + ([Commit](https://github.com/rails/rails/commit/bfaa3091c3c32b5980a614ef0f7b39cbf83f6db3)) + +* Rename `Array#without` and `Enumerable#without` to `Array#excluding` + and `Enumerable#excluding`. Old method names are retained as aliases. + ([Commit](https://github.com/rails/rails/commit/bfaa3091c3c32b5980a614ef0f7b39cbf83f6db3)) + +* Add support for supplying `locale` to `transliterate` and `parameterize`. + ([Pull Request](https://github.com/rails/rails/pull/35571)) + +* Fix `Time#advance` to work with dates before 1001-03-07. + ([Pull Request](https://github.com/rails/rails/pull/35659)) + +* Update `ActiveSupport::Notifications::Instrumenter#instrument` to allow + not passing block. + ([Pull Request](https://github.com/rails/rails/pull/35705)) + +* Use weak references in descendants tracker to allow anonymous subclasses to + be garbage collected. + ([Pull Request](https://github.com/rails/rails/pull/31442)) + +* Calling test methods with `with_info_handler` method to allow minitest-hooks + plugin to work. + ([Commit](https://github.com/rails/rails/commit/758ba117a008b6ea2d3b92c53b6a7a8d7ccbca69)) + +* Preserve `html_safe?` status on `ActiveSupport::SafeBuffer#*`. + ([Pull Request](https://github.com/rails/rails/pull/36012)) + Active Job ---------- diff --git a/guides/source/action_text_overview.md b/guides/source/action_text_overview.md index 08ec35e52a..07919775e2 100644 --- a/guides/source/action_text_overview.md +++ b/guides/source/action_text_overview.md @@ -91,7 +91,7 @@ end By default, the Action Text editor and content is styled by the Trix defaults. If you want to change these defaults, you'll want to remove -the `app/assets/stylesheets/actiontext.css` linker and base your stylings on +the `app/assets/stylesheets/actiontext.scss` linker and base your stylings on the [contents of that file](https://raw.githubusercontent.com/basecamp/trix/master/dist/trix.css). You can also style the HTML used for embedded images and other attachments (known as blobs). diff --git a/guides/source/active_record_migrations.md b/guides/source/active_record_migrations.md index 270e4a3bf9..9398244ccf 100644 --- a/guides/source/active_record_migrations.md +++ b/guides/source/active_record_migrations.md @@ -225,6 +225,8 @@ class CreateProducts < ActiveRecord::Migration[5.0] create_table :products do |t| t.string :name t.string :part_number + + t.timestamps end end end diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index e68f34dd5d..f904d4de65 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -664,7 +664,7 @@ This helper passes the record to a separate class for validation. class GoodnessValidator < ActiveModel::Validator def validate(record) if record.first_name == "Evil" - record.errors[:base] << "This person is evil" + record.errors.add :base, "This person is evil" end end end @@ -692,7 +692,7 @@ validator class as `options`: class GoodnessValidator < ActiveModel::Validator def validate(record) if options[:fields].any?{|field| record.send(field) == "Evil" } - record.errors[:base] << "This person is evil" + record.errors.add :base, "This person is evil" end end end @@ -723,7 +723,7 @@ class GoodnessValidator def validate if some_complex_condition_involving_ivars_and_private_methods? - @person.errors[:base] << "This person is evil" + @person.errors.add :base, "This person is evil" end end @@ -1004,7 +1004,7 @@ and performs the validation on it. The custom validator is called using the class MyValidator < ActiveModel::Validator def validate(record) unless record.name.starts_with? 'X' - record.errors[:name] << 'Need a name starting with X please!' + record.errors.add :name, "Need a name starting with X please!" end end end @@ -1026,7 +1026,7 @@ instance. class EmailValidator < ActiveModel::EachValidator def validate_each(record, attribute, value) unless value =~ /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i - record.errors[attribute] << (options[:message] || "is not an email") + record.errors.add attribute, (options[:message] || "is not an email") end end end @@ -1203,7 +1203,7 @@ You can add error messages that are related to the object's state as a whole, in ```ruby class Person < ApplicationRecord def a_method_used_for_validation_purposes - errors[:base] << "This person is invalid because ..." + errors.add :base, "This person is invalid because ..." end end ``` diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md index 615f576797..2986850cef 100644 --- a/guides/source/active_storage_overview.md +++ b/guides/source/active_storage_overview.md @@ -189,14 +189,21 @@ gem "google-cloud-storage", "~> 1.11", require: false ### Mirror Service -You can keep multiple services in sync by defining a mirror service. When a file -is uploaded or deleted, it's done across all the mirrored services. Mirrored -services can be used to facilitate a migration between services in production. -You can start mirroring to the new service, copy existing files from the old -service to the new, then go all-in on the new service. Define each of the -services you'd like to use as described above and reference them from a mirrored +You can keep multiple services in sync by defining a mirror service. A mirror +service replicates uploads and deletes across two or more subordinate services. + +A mirror service is intended to be used temporarily during a migration between +services in production. You can start mirroring to a new service, copy +pre-existing files from the old service to the new, then go all-in on the new service. +NOTE: Mirroring is not atomic. It is possible for an upload to succeed on the +primary service and fail on any of the subordinate services. Before going +all-in on a new service, verify that all files have been copied. + +Define each of the services you'd like to mirror as described above. Reference +them by name when defining a mirror service: + ```yaml s3_west_coast: service: S3 @@ -219,9 +226,12 @@ production: - s3_west_coast ``` -NOTE: Files are served from the primary service. +Although all secondary services receive uploads, downloads are always handled +by the primary service. -NOTE: This is not compatible with the [direct uploads](#direct-uploads) feature. +Mirror services are compatible with direct uploads. New files are directly +uploaded to the primary service. When a directly-uploaded file is attached to a +record, a background job is enqueued to copy it to the secondary services. Attaching Files to Records -------------------------- diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index 1a057832d4..21901a7158 100644 --- a/guides/source/active_support_core_extensions.md +++ b/guides/source/active_support_core_extensions.md @@ -2633,14 +2633,12 @@ The method `stringify_keys` returns a hash that has a stringified version of the # => {"" => nil, "1" => 1, "a" => :a} ``` -In case of key collision, one of the values will be chosen. The chosen value may not always be the same given the same hash: +In case of key collision, the value will be the one most recently inserted into the hash: ```ruby {"a" => 1, a: 2}.stringify_keys -# The result could either be +# The result will be # => {"a"=>2} -# or -# => {"a"=>1} ``` This method may be useful for example to easily accept both symbols and strings as options. For instance `ActionView::Helpers::FormHelper` defines: @@ -2677,14 +2675,12 @@ The method `symbolize_keys` returns a hash that has a symbolized version of the WARNING. Note in the previous example only one key was symbolized. -In case of key collision, one of the values will be chosen. The chosen value may not always be the same given the same hash: +In case of key collision, the value will be the one most recently inserted into the hash: ```ruby {"a" => 1, a: 2}.symbolize_keys -# The result could either be +# The result will be # => {:a=>2} -# or -# => {:a=>1} ``` This method may be useful for example to easily accept both symbols and strings as options. For instance `ActionController::UrlRewriter` defines diff --git a/guides/source/active_support_instrumentation.md b/guides/source/active_support_instrumentation.md index 4868b00bbe..9f15e70da6 100644 --- a/guides/source/active_support_instrumentation.md +++ b/guides/source/active_support_instrumentation.md @@ -643,7 +643,16 @@ The block receives the following arguments: ```ruby ActiveSupport::Notifications.subscribe "process_action.action_controller" do |name, started, finished, unique_id, data| # your own custom stuff - Rails.logger.info "#{name} Received!" + Rails.logger.info "#{name} Received! (started: #{started}, finished: #{finished})" # process_action.action_controller Received (started: 2019-05-05 13:43:57 -0800, finished: 2019-05-05 13:43:58 -0800) +end +``` + +If you are concerned about the accuracy of `started` and `finished` to compute a precise elapsed time then use `ActiveSupport::Notifications.monotonic_subscribe`. The given block would receive the same arguments as above but the `started` and `finished` will have values with an accurate monotonic time instead of wall-clock time. + +```ruby +ActiveSupport::Notifications.monotonic_subscribe "process_action.action_controller" do |name, started, finished, unique_id, data| + # your own custom stuff + Rails.logger.info "#{name} Received! (started: #{started}, finished: #{finished})" # process_action.action_controller Received (started: 1560978.425334, finished: 1560979.429234) end ``` diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md index a60ce7fb32..27387ac3ac 100644 --- a/guides/source/association_basics.md +++ b/guides/source/association_basics.md @@ -1231,6 +1231,7 @@ The `has_one` association supports these options: * `:source` * `:source_type` * `:through` +* `:touch` * `:validate` ##### `:as` @@ -1324,6 +1325,28 @@ class DustJacket < ApplicationRecord; end The `:through` option specifies a join model through which to perform the query. `has_one :through` associations were discussed in detail [earlier in this guide](#the-has-one-through-association). +##### `:touch` + +If you set the `:touch` option to `true`, then the `updated_at` or `updated_on` timestamp on the associated object will be set to the current time whenever this object is saved or destroyed: + +```ruby +class Supplier < ApplicationRecord + has_one :account, touch: true +end + +class Account < ApplicationRecord + belongs_to :supplier +end +``` + +In this case, saving or destroying a supplier will update the timestamp on the associated account. You can also specify a particular timestamp attribute to update: + +```ruby +class Supplier < ApplicationRecord + has_one :account, touch: :suppliers_updated_at +end +``` + ##### `:validate` If you set the `:validate` option to `true`, then associated objects will be validated whenever you save this object. By default, this is `false`: associated objects will not be validated when this object is saved. @@ -2383,11 +2406,11 @@ NOTE: These callbacks are called only when the associated objects are added or r ```ruby # Triggers `before_add` callback -author.books << book +author.books << book author.books = [book, book2] # Does not trigger the `before_add` callback -book.update(author_id: 1) +book.update(author_id: 1) ``` ### Association Extensions @@ -2428,8 +2451,8 @@ Extensions can refer to the internals of the association proxy using these three * `proxy_association.reflection` returns the reflection object that describes the association. * `proxy_association.target` returns the associated object for `belongs_to` or `has_one`, or the collection of associated objects for `has_many` or `has_and_belongs_to_many`. -Single Table Inheritance ------------------------- +Single Table Inheritance (STI) +------------------------------ Sometimes, you may want to share fields and behavior between different models. Let's say we have Car, Motorcycle, and Bicycle models. We will want to share diff --git a/guides/source/command_line.md b/guides/source/command_line.md index 4ad143d105..4681574edd 100644 --- a/guides/source/command_line.md +++ b/guides/source/command_line.md @@ -92,6 +92,28 @@ $ rails new commandsapp Rails will set you up with what seems like a huge amount of stuff for such a tiny command! You've got the entire Rails directory structure now with all the code you need to run our simple application right out of the box. +If you wish to skip some files or components from being generated, you can append the following arguments to your `rails new` command: + +| Argument | Description | +| ----------------------- | ----------------------------------------------------------- | +| `--skip-gemfile` | Don't create a Gemfile | +| `--skip-git` | Skip .gitignore file | +| `--skip-keeps` | Skip source control .keep files | +| `--skip-action-mailer` | Skip Action Mailer files | +| `--skip-action-text` | Skip Action Text gem | +| `--skip-active-record` | Skip Active Record files | +| `--skip-active-storage` | Skip Active Storage files | +| `--skip-puma` | Skip Puma related files | +| `--skip-action-cable` | Skip Action Cable files | +| `--skip-sprockets` | Skip Sprockets files | +| `--skip-spring` | Don't install Spring application preloader | +| `--skip-listen` | Don't generate configuration that depends on the listen gem | +| `--skip-javascript` | Skip JavaScript files | +| `--skip-turbolinks` | Skip turbolinks gem | +| `--skip-test` | Skip test files | +| `--skip-system-test` | Skip system test files | +| `--skip-bootsnap` | Skip bootsnap gem | + ### `rails server` The `rails server` command launches a web server named Puma which comes bundled with Rails. You'll use this any time you want to access your application through a web browser. @@ -238,14 +260,17 @@ Usage: ... -Active Record options: - [--migration] # Indicates when to generate migration - # Default: true +ActiveRecord options: + [--migration], [--no-migration] # Indicates when to generate migration + # Default: true ... Description: - Create rails files for model generator. + Stubs out a new model. Pass the model name, either CamelCased or + under_scored, and an optional list of attribute pairs as arguments. + +... ``` NOTE: For a list of available field types for the `type` parameter, refer to the [API documentation](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_column) for the add_column method for the `SchemaStatements` module. The `index` parameter generates a corresponding index for the column. diff --git a/guides/source/configuring.md b/guides/source/configuring.md index 42da654fe7..cc64c7eac6 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -64,10 +64,12 @@ These configuration methods are to be called on a `Rails::Railtie` object, such * `config.autoload_paths` accepts an array of paths from which Rails will autoload constants. Default is all directories under `app`. It is no longer recommended to adjust this. See [Autoloading and Reloading Constants](autoloading_and_reloading_constants.html#autoload-paths-and-eager-load-paths) +* `config.add_autoload_paths_to_load_path` says whether autoload paths have to be added to `$LOAD_PATH`. This flag is `true` by default, but it is recommended to be set to `false` in `:zeitwerk` mode early, in `config/application.rb`. Zeitwerk uses absolute paths internally, and applications running in `:zeitwerk` mode do not need `require_dependency`, so models, controllers, jobs, etc. do not need to be in `$LOAD_PATH`. Setting this to `false` saves Ruby from checking these directories when resolving `require` calls with relative paths, and saves Bootsnap work and RAM, since it does not need to build an index for them. + * `config.cache_classes` controls whether or not application classes and modules should be reloaded on each request. Defaults to `false` in development mode, and `true` in test and production modes. * `config.beginning_of_week` sets the default beginning of week for the -application. Accepts a valid week day symbol (e.g. `:monday`). +application. Accepts a valid day of week as a symbol (e.g. `:monday`). * `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`, `:redis_cache_store`, or an object that implements the cache API. Defaults to `:file_store`. @@ -143,7 +145,7 @@ defaults to `:debug` for all environments. The available log levels are: `:debug * `secret_key_base` is used for specifying a key which allows sessions for the application to be verified against a known secure key to prevent tampering. Applications get a random generated key in test and development environments, other environments should set one in `config/credentials.yml.enc`. -* `config.public_file_server.enabled` configures Rails to serve static files from the public directory. This option defaults to `true`, but in the production environment it is set to `false` because the server software (e.g. NGINX or Apache) used to run the application should serve static files instead. If you are running or testing your app in production mode using WEBrick (it is not recommended to use WEBrick in production) set the option to `true.` Otherwise, you won't be able to use page caching and request for files that exist under the public directory. +* `config.public_file_server.enabled` configures Rails to serve static files from the public directory. This option defaults to `true`, but in the production environment it is set to `false` because the server software (e.g. NGINX or Apache) used to run the application should serve static files instead. If you are running or testing your app in production mode using WEBrick (it is not recommended to use WEBrick in production) set the option to `true`. Otherwise, you won't be able to use page caching and request for files that exist under the public directory. * `config.session_store` 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. Defaults to a cookie store with application name as the session key. Custom session stores can also be specified: @@ -155,6 +157,13 @@ defaults to `:debug` for all environments. The available log levels are: `:debug * `config.time_zone` sets the default time zone for the application and enables time zone awareness for Active Record. +* `config.autoloader` sets the autoloading mode. This option defaults to `:zeitwerk` if `6.0` is specified in `config.load_defaults`. Applications can still use the classic autoloader by setting this value to `:classic` after loading the framework defaults: + + ```ruby + config.load_defaults "6.0" + config.autoloader = :classic + ``` + ### Configuring Assets * `config.assets.enabled` a flag that controls whether the asset @@ -381,6 +390,12 @@ All these configuration options are delegated to the `I18n` library. having to send a query to the database to get this information. Defaults to `true`. +* `config.active_record.collection_cache_versioning` enables the same cache key + to be reused when the object being cached of type `ActiveRecord::Relation` + changes by moving the volatile information (max updated at and count) of + the relation's cache key into the cache version to support recycling cache key. + Defaults to `false`. + The MySQL adapter adds one additional configuration option: * `ActiveRecord::ConnectionAdapters::Mysql2Adapter.emulate_booleans` controls whether Active Record will consider all `tinyint(1)` columns as booleans. Defaults to `true`. @@ -837,6 +852,12 @@ text/javascript image/svg+xml application/postscript application/x-shockwave-fla config.active_storage.queues.purge = :low_priority ``` +* `config.active_storage.queues.mirror` accepts a symbol indicating the Active Job queue to use for direct upload mirroring jobs. The default is `:active_storage_mirror`. + + ```ruby + config.active_storage.queues.mirror = :low_priority + ``` + * `config.active_storage.logger` can be used to set the logger used by Active Storage. Accepts a logger conforming to the interface of Log4r or the default Ruby Logger class. ```ruby @@ -884,12 +905,14 @@ text/javascript image/svg+xml application/postscript application/x-shockwave-fla #### With '6.0': +- `config.autoloader`: `:zeitwerk` - `config.action_view.default_enforce_utf8`: `false` - `config.action_dispatch.use_cookies_with_metadata`: `true` - `config.action_mailer.delivery_job`: `"ActionMailer::MailDeliveryJob"` - `config.active_job.return_false_on_aborted_enqueue`: `true` - `config.active_storage.queues.analysis`: `:active_storage_analysis` - `config.active_storage.queues.purge`: `:active_storage_purge` +- `config.active_record.collection_cache_versioning`: `true` ### Configuring a Database diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index f86589bdf1..a6eb9907a0 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -340,7 +340,7 @@ $ TEST_DIR=generators bundle exec rake test You can run the tests for a particular file by using: ```bash -$ cd actionpack +$ cd actionview $ bundle exec ruby -w -Itest test/template/form_helper_test.rb ``` diff --git a/guides/source/engines.md b/guides/source/engines.md index 3031c62928..90b08b00f0 100644 --- a/guides/source/engines.md +++ b/guides/source/engines.md @@ -1511,34 +1511,35 @@ These are the hooks you can use in your own code. To hook into the initialization process of one of the following classes use the available hook. -| Class | Available Hooks | -| --------------------------------- | ------------------------------------ | -| `ActionCable` | `action_cable` | -| `ActionCable::Channel::Base` | `action_cable_channel` | -| `ActionCable::Connection::Base` | `action_cable_connection` | -| `ActionController::API` | `action_controller_api` | -| `ActionController::API` | `action_controller` | -| `ActionController::Base` | `action_controller_base` | -| `ActionController::Base` | `action_controller` | -| `ActionController::TestCase` | `action_controller_test_case` | -| `ActionDispatch::IntegrationTest` | `action_dispatch_integration_test` | -| `ActionDispatch::SystemTestCase` | `action_dispatch_system_test_case` | -| `ActionMailbox::Base` | `action_mailbox` | -| `ActionMailbox::InboundEmail` | `action_mailbox_inbound_email` | -| `ActionMailbox::TestCase` | `action_mailbox_test_case` | -| `ActionMailer::Base` | `action_mailer` | -| `ActionMailer::TestCase` | `action_mailer_test_case` | -| `ActionText::Content` | `action_text_content` | -| `ActionText::RichText` | `action_text_rich_text` | -| `ActionView::Base` | `action_view` | -| `ActionView::TestCase` | `action_view_test_case` | -| `ActiveJob::Base` | `active_job` | -| `ActiveJob::TestCase` | `active_job_test_case` | -| `ActiveRecord::Base` | `active_record` | -| `ActiveStorage::Attachment` | `active_storage_attachment` | -| `ActiveStorage::Blob` | `active_storage_blob` | -| `ActiveSupport::TestCase` | `active_support_test_case` | -| `i18n` | `i18n` | +| Class | Available Hooks | +| -------------------------------------| ------------------------------------ | +| `ActionCable` | `action_cable` | +| `ActionCable::Channel::Base` | `action_cable_channel` | +| `ActionCable::Connection::Base` | `action_cable_connection` | +| `ActionCable::Connection::TestCase` | `action_cable_connection_test_case` | +| `ActionController::API` | `action_controller_api` | +| `ActionController::API` | `action_controller` | +| `ActionController::Base` | `action_controller_base` | +| `ActionController::Base` | `action_controller` | +| `ActionController::TestCase` | `action_controller_test_case` | +| `ActionDispatch::IntegrationTest` | `action_dispatch_integration_test` | +| `ActionDispatch::SystemTestCase` | `action_dispatch_system_test_case` | +| `ActionMailbox::Base` | `action_mailbox` | +| `ActionMailbox::InboundEmail` | `action_mailbox_inbound_email` | +| `ActionMailbox::TestCase` | `action_mailbox_test_case` | +| `ActionMailer::Base` | `action_mailer` | +| `ActionMailer::TestCase` | `action_mailer_test_case` | +| `ActionText::Content` | `action_text_content` | +| `ActionText::RichText` | `action_text_rich_text` | +| `ActionView::Base` | `action_view` | +| `ActionView::TestCase` | `action_view_test_case` | +| `ActiveJob::Base` | `active_job` | +| `ActiveJob::TestCase` | `active_job_test_case` | +| `ActiveRecord::Base` | `active_record` | +| `ActiveStorage::Attachment` | `active_storage_attachment` | +| `ActiveStorage::Blob` | `active_storage_blob` | +| `ActiveSupport::TestCase` | `active_support_test_case` | +| `i18n` | `i18n` | ## Configuration hooks diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index e486c53fe3..e8b224a1a3 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -126,7 +126,7 @@ run the following: $ rails --version ``` -If it says something like "Rails 5.2.1", you are ready to continue. +If it says something like "Rails 6.0.0", you are ready to continue. ### Creating the Blog Application @@ -205,12 +205,10 @@ $ rails server TIP: If you are using Windows, you have to pass the scripts under the `bin` folder directly to the Ruby interpreter e.g. `ruby bin\rails server`. -TIP: Compiling CoffeeScript and JavaScript asset compression requires you +TIP: JavaScript asset compression requires you have a JavaScript runtime available on your system, in the absence -of a runtime you will see an `execjs` error during asset compilation. +of a runtime you will see an `execjs` error during asset compression. Usually macOS and Windows come with a JavaScript runtime installed. -Rails adds the `mini_racer` gem to the generated `Gemfile` in a -commented line for new apps and you can uncomment if you need it. `therubyrhino` is the recommended runtime for JRuby users and is added by default to the `Gemfile` in apps generated under JRuby. You can investigate all the supported runtimes at [ExecJS](https://github.com/rails/execjs#readme). @@ -1560,7 +1558,7 @@ class CreateComments < ActiveRecord::Migration[6.0] create_table :comments do |t| t.string :commenter t.text :body - t.references :article, foreign_key: true + t.references :article, null: false, foreign_key: true t.timestamps end diff --git a/guides/source/i18n.md b/guides/source/i18n.md index d6fccadb28..5d91a6df33 100644 --- a/guides/source/i18n.md +++ b/guides/source/i18n.md @@ -992,27 +992,6 @@ So, for example, instead of the default error message `"cannot be blank"` you co | numericality | :odd | :odd | - | | numericality | :even | :even | - | -#### Translations for the Active Record `error_messages_for` Helper - -If you are using the Active Record `error_messages_for` helper, you will want to add -translations for it. - -Rails ships with the following translations: - -```yaml -en: - activerecord: - errors: - template: - header: - one: "1 error prohibited this %{model} from being saved" - other: "%{count} errors prohibited this %{model} from being saved" - body: "There were problems with the following fields:" -``` - -NOTE: In order to use this helper, you need to install [DynamicForm](https://github.com/joelmoss/dynamic_form) -gem by adding this line to your `Gemfile`: `gem 'dynamic_form'`. - ### Translations for Action Mailer E-Mail Subjects If you don't pass a subject to the `mail` method, Action Mailer will try to find diff --git a/guides/source/routing.md b/guides/source/routing.md index e3a6bbb138..4aeb9ee585 100644 --- a/guides/source/routing.md +++ b/guides/source/routing.md @@ -508,7 +508,7 @@ end This will recognize `/photos/1/preview` with GET, and route to the `preview` action of `PhotosController`, with the resource id value passed in `params[:id]`. It will also create the `preview_photo_url` and `preview_photo_path` helpers. -Within the block of member routes, each route name specifies the HTTP verb +Within the block of member routes, each route name specifies the HTTP verb that will be recognized. You can use `get`, `patch`, `put`, `post`, or `delete` here . If you don't have multiple `member` routes, you can also pass `:on` to a route, eliminating the block: diff --git a/guides/source/testing.md b/guides/source/testing.md index 26448958ea..9540bb2af5 100644 --- a/guides/source/testing.md +++ b/guides/source/testing.md @@ -781,7 +781,7 @@ This can be helpful for viewing the browser at the point a test failed, or to view screenshots later for debugging. Two methods are provided: `take_screenshot` and `take_failed_screenshot`. -`take_failed_screenshot` is automatically included in `after_teardown` inside +`take_failed_screenshot` is automatically included in `before_teardown` inside Rails. The `take_screenshot` helper method can be included anywhere in your tests to @@ -1212,7 +1212,7 @@ Let's start by adding this assertion to our `test_should_create_article` test: ```ruby test "should create article" do assert_difference('Article.count') do - post article_url, params: { article: { title: 'Some title' } } + post articles_url, params: { article: { title: 'Some title' } } end assert_redirected_to article_path(Article.last) diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index 79bad8f4ed..b8a5c39f39 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -85,30 +85,31 @@ 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. -### Purpose in signed or encrypted cookie is now embedded in the cookies values +### Purpose and expiry metadata is now embedded inside signed and encrypted cookies for increased security -To improve security, Rails now embeds the purpose information in encrypted or signed cookies value. -Rails can now thwart attacks that attempt to copy signed/encrypted value +To improve security, Rails embeds the purpose and expiry metadata inside encrypted or signed cookies value. + +Rails can then thwart attacks that attempt to copy the signed/encrypted value of a cookie and use it as the value of another cookie. -This new embed information make those cookies incompatible with versions of Rails older than 6.0. +This new embed metadata make those cookies incompatible with versions of Rails older than 6.0. -If you require your cookies to be read by 5.2 and older, or you are still validating your 6.0 deploy and want -to allow you to rollback set +If you require your cookies to be read by Rails 5.2 and older, or you are still validating your 6.0 deploy and want +to be able to rollback set `Rails.application.config.action_dispatch.use_cookies_with_metadata` to `false`. -### ActionCable javascript API Changes +### Action Cable JavaScript API Changes -The ActionCable javascript package has been converted from CoffeeScript +The Action Cable JavaScript package has been converted from CoffeeScript to ES2015, and we now publish the source code in the npm distribution. -This change includes some breaking changes to optional parts of the -ActionCable javascript API: +This release includes some breaking changes to optional parts of the +Action Cable JavaScript API: - Configuration of the WebSocket adapter and logger adapter have been moved from properties of `ActionCable` to properties of `ActionCable.adapters`. - If you are currently configuring these adapters you will need to make - these changes when upgrading: + If you are configuring these adapters you will need to make + these changes: ```diff - ActionCable.WebSocket = MyWebSocket @@ -121,8 +122,8 @@ ActionCable javascript API: - The `ActionCable.startDebugging()` and `ActionCable.stopDebugging()` methods have been removed and replaced with the property - `ActionCable.logger.enabled`. If you are currently using these methods you - will need to make these changes when upgrading: + `ActionCable.logger.enabled`. If you are using these methods you + will need to make these changes: ```diff - ActionCable.startDebugging() @@ -133,6 +134,252 @@ ActionCable javascript API: + ActionCable.logger.enabled = false ``` +### Autoloading + +The default configuration for Rails 6 + +```ruby +# config/application.rb + +config.load_defaults "6.0" +``` + +enables `zeitwerk` autoloading mode on CRuby. In that mode, autoloading, reloading, and eager loading are managed by [Zeitwerk](https://github.com/fxn/zeitwerk). + +#### Public API + +In general, applications do not need to use the API of Zeitwerk directly. Rails sets things up according to the existing contract: `config.autoload_paths`, `config.cache_classes`, etc. + +While applications should stick to that interface, the actual Zeitwerk loader object can be accessed as + +```ruby +Rails.autoloaders.main +``` + +That may be handy if you need to preload STIs or configure a custom inflector, for example. + +#### Project Structure + +If the application being upgraded autoloads correctly, the project structure should be already mostly compatible. + +However, `classic` mode infers file names from missing constant names (`underscore`), whereas `zeitwerk` mode infers constant names from file names (`camelize`). These helpers are not always inverse of each other, in particular if acronyms are involved. For instance, `"FOO".underscore` is `"foo"`, but `"foo".camelize` is `"Foo"`, not `"FOO"`. Compatibility can be checked by setting `classic` mode first temporarily: + +```ruby +# config/application.rb + +config.load_defaults "6.0" +config.autoloader = :classic +``` + +and then running + +``` +bin/rails zeitwerk:check +``` + +When all is good, you can delete `config.autoloader = :classic`. + +#### require_dependency + +All known use cases of `require_dependency` have been eliminated, you should grep the project and delete them. + +In the case of STIs with a hierarchy of more than two levels, you can preload the leaves of the hierarchy in an initializer: + +```ruby +# config/initializers/preload_stis.rb + +# By preloading leaves, the hierarchy is loaded upwards following +# the references to superclasses in the class definitions. +sti_leaves = %w( + app/models/leaf1.rb + app/models/leaf2.rb + app/models/leaf3.rb +) +Rails.autoloaders.main.preload(sti_leaves) +``` + +#### Qualified names in class and module definitions + +You can now robustly use constant paths in class and module definitions: + +```ruby +# Autoloading in this class' body matches Ruby semantics now. +class Admin::UsersController < ApplicationController + # ... +end +``` + +A gotcha to be aware of is that, depending on the order of execution, the classic autoloader could sometimes be able to autoload `Foo::Wadus` in + +```ruby +class Foo::Bar + Wadus +end +``` + +That does not match Ruby semantics because `Foo` is not in the nesting, and won't work at all in `zeitwerk` mode. If you find such corner case you can use the qualified name `Foo::Wadus`: + +```ruby +class Foo::Bar + Foo::Wadus +end +``` + +or add `Foo` to the nesting: + +```ruby +module Foo + class Bar + Wadus + end +end +``` + +#### Concerns + +You can autoload and eager load from a standard structure like + +``` +app/models +app/models/concerns +``` + +In that case, `app/models/concerns` is assumed to be a root directory (because it belongs to the autoload paths), and it is ignored as namespace. So, `app/models/concerns/foo.rb` should define `Foo`, not `Concerns::Foo`. + +The `Concerns::` namespace worked with the classic autoloader as a side-effect of the implementation, but it was not really an intended behavior. An application using `Concerns::` needs to rename those classes and modules to be able to run in `zeitwerk` mode. + +#### Autoloaded Constants and Explicit Namespaces + +If a namespace is defined in a file, as `Hotel` is here: + +``` +app/models/hotel.rb # Defines Hotel. +app/models/hotel/pricing.rb # Defines Hotel::Pricing. +``` + +the `Hotel` constant has to be set using the `class` or `module` keywords. For example: + +```ruby +class Hotel +end +``` + +is good. + +Alternatives like + +```ruby +Hotel = Class.new +``` + +or + +```ruby +Hotel = Struct.new +``` + +won't work, child objects like `Hotel::Pricing` won't be found. + +This restriction only applies to explicit namespaces. Classes and modules not defining a namespace can be defined using those idioms. + +#### One file, one constant (at the same top-level) + +In `classic` mode you could technically define several constants at the same top-level and have them all reloaded. For example, given + +```ruby +# app/models/foo.rb + +class Foo +end + +class Bar +end +``` + +while `Bar` could not be autoloaded, autoloading `Foo` would mark `Bar` as autoloaded too. This is not the case in `zeitwerk` mode, you need to move `Bar` to its own file `bar.rb`. One file, one constant. + +This affects only to constants at the same top-level as in the example above. Inner classes and modules are fine. For example, consider + +```ruby +# app/models/foo.rb + +class Foo + class InnerClass + end +end +``` + +If the application reloads `Foo`, it will reload `Foo::InnerClass` too. + +#### Spring and the `test` Environment + +Spring reloads the application code if something changes. In the `test` environment you need to enable reloading for that to work: + +```ruby +# config/environments/test.rb + +config.cache_classes = false +``` + +Otherwise you'll get this error: + +``` +reloading is disabled because config.cache_classes is true +``` + +#### Bootsnap + +Bootsnap should be at least version 1.4.2. + +In addition to that, Bootsnap needs to disable the iseq cache due to a bug in the interpreter if running Ruby 2.5. Please make sure to depend on at least Bootsnap 1.4.4 in that case. + +#### `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`. + +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. + +#### 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 `development` mode. + +Constant autoloading is thread-safe in `zeitwerk` mode. For example, you can now autoload in multi-threaded scripts executed by the `runner` command. + +#### Globs in config.autoload_paths + +Beware of configurations like + +```ruby +config.autoload_paths += Dir["#{config.root}/lib/**/"] +``` + +Every element of `config.autoload_paths` should represent the top-level namespace (`Object`) and they cannot be nested in consequence (with the exception of `concerns` directories explained above). + +To fix this, just remove the wildcards: + +```ruby +config.autoload_paths << "#{config.root}/lib" +``` + +#### How to Use the Classic Autoloader in Rails 6 + +Applications can load Rails 6 defaults and still use the classic autoloader by setting `config.autoloader` this way: + +```ruby +# config/application.rb + +config.load_defaults "6.0" +config.autoloader = :classic +``` + Upgrading from Rails 5.1 to Rails 5.2 ------------------------------------- @@ -1557,7 +1804,7 @@ config.assets.enabled = true config.assets.version = '1.0' ``` -If your application is using an "/assets" route for a resource you may want change the prefix used for assets to avoid conflicts: +If your application is using an "/assets" route for a resource you may want to change the prefix used for assets to avoid conflicts: ```ruby # Defaults to '/assets' |