diff options
Diffstat (limited to 'guides/source/upgrading_ruby_on_rails.md')
| -rw-r--r-- | guides/source/upgrading_ruby_on_rails.md | 141 |
1 files changed, 108 insertions, 33 deletions
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index cbe46d6c0d..c41876cd28 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -75,9 +75,9 @@ For more information on changes made to Rails 5.0 please see the [release notes] From Ruby on Rails 5.0 onwards, Ruby 2.2.2+ is the only supported Ruby version. Make sure you are on Ruby 2.2.2 version or greater, before you proceed. -### Active Record models now inherit from ApplicationRecord by default +### Active Record Models Now Inherit from ApplicationRecord by Default -In Rails 4.2 an Active Record model inherits from `ActiveRecord::Base`. In Rails 5.0, +In Rails 4.2, an Active Record model inherits from `ActiveRecord::Base`. In Rails 5.0, all models inherit from `ApplicationRecord`. `ApplicationRecord` is a new superclass for all app models, analogous to app @@ -85,7 +85,7 @@ controllers subclassing `ApplicationController` instead of `ActionController::Base`. This gives apps a single spot to configure app-wide model behavior. -When upgrading from Rails 4.2 to Rails 5.0 you need to create an +When upgrading from Rails 4.2 to Rails 5.0, you need to create an `application_record.rb` file in `app/models/` and add the following content: ``` @@ -94,7 +94,7 @@ class ApplicationRecord < ActiveRecord::Base end ``` -### Halting callback chains via `throw(:abort)` +### Halting Callback Chains via `throw(:abort)` In Rails 4.2, when a 'before' callback returns `false` in Active Record and Active Model, then the entire callback chain is halted. In other words, @@ -119,12 +119,12 @@ halted the chain when any value was returned. See [#17227](https://github.com/rails/rails/pull/17227) for more details. -### ActiveJob jobs now inherit from ApplicationJob by default +### ActiveJob Now Inherits from ApplicationJob by Default -In Rails 4.2 an Active Job inherits from `ActiveJob::Base`. In Rails 5.0 this +In Rails 4.2, an Active Job inherits from `ActiveJob::Base`. In Rails 5.0, this behavior has changed to now inherit from `ApplicationJob`. -When upgrading from Rails 4.2 to Rails 5.0 you need to create an +When upgrading from Rails 4.2 to Rails 5.0, you need to create an `application_job.rb` file in `app/jobs/` and add the following content: ``` @@ -139,25 +139,41 @@ See [#19034](https://github.com/rails/rails/pull/19034) for more details. ### Rails Controller Testing `assigns` and `assert_template` have been extracted to the `rails-controller-testing` gem. To -continue using these methods in your controller tests add `gem 'rails-controller-testing'` to +continue using these methods in your controller tests, add `gem 'rails-controller-testing'` to your Gemfile. -If you are using Rspec for testing please see the extra configuration required in the gem's +If you are using Rspec for testing, please see the extra configuration required in the gem's documentation. +### Autoloading is Disabled After Booting in the Production Environment + +Autoloading is now disabled after booting in the production environment by +default. + +Eager loading the application is part of the boot process, so top-level +constants are fine and are still autoloaded, no need to require their files. + +Constants in deeper places only executed at runtime, like regular method bodies, +are also fine because the file defining them will have been eager loaded while booting. + +For the vast majority of applications this change needs no action. But in the +very rare event that your application needs autoloading while running in +production mode, set `Rails.application.config.enable_dependency_loading` to +true. + ### XML Serialization `ActiveModel::Serializers::Xml` has been extracted from Rails to the `activemodel-serializers-xml` -gem. To continue using XML serialization in your application add `gem 'activemodel-serializers-xml'` +gem. To continue using XML serialization in your application, add `gem 'activemodel-serializers-xml'` to your Gemfile. -### Removed support for legacy MySQL +### Removed Support for Legacy `mysql` Database Adapter Rails 5 removes support for the legacy `mysql` database adapter. Most users should be able to use `mysql2` instead. It will be converted to a separate gem when we find someone to maintain it. -### Removed support for debugger +### Removed Support for Debugger `debugger` is not supported by Ruby 2.2 which is required by Rails 5. Use `byebug` instead. @@ -168,27 +184,27 @@ these changes are in parallel with rake, but some were ported over altogether. To use the new test runner simply type `bin/rails test`. - rake dev:cache` is now `rails dev:cache +`rake dev:cache` is now `rails dev:cache`. Run `bin/rails` to see the list of commands available. -### `ActionController::Parameters` no longer inherits from `HashWithIndifferentAccess` +### `ActionController::Parameters` No Longer Inherits from `HashWithIndifferentAccess` Calling `params` in your application will now return an object instead of a hash. If your -parameters are already permitted you will not need to make any changes. If you are using slice +parameters are already permitted, then you will not need to make any changes. If you are using `slice` and other methods that depend on being able to read the hash regardless of `permitted?` you will need to upgrade your application to first permit and then convert to a hash. params.permit([:proceed_to, :return_to]).to_h -### `protect_from_forgery` now defaults to `prepend: false` +### `protect_from_forgery` Now Defaults to `prepend: false` `protect_from_forgery` defaults to `prepend: false` which means that it will be inserted into the callback chain at the point in which you call it in your application. If you want -`protect_from_forgery` to always run first you should change your application to use +`protect_from_forgery` to always run first, then you should change your application to use `protect_from_forgery prepend: true`. -### Default template handler is now RAW +### Default Template Handler is Now RAW Files without a template handler in their extension will be rendered using the raw handler. Previously Rails would render files using the ERB template handler. @@ -196,9 +212,9 @@ Previously Rails would render files using the ERB template handler. If you do not want your file to be handled via the raw handler, you should add an extension to your file that can be parsed by the appropriate template handler. -### Add wildcard matching for template dependencies +### Added Wildcard Matching for Template Dependencies -You can now use wildcard matching for your template dependencies. For example if you were +You can now use wildcard matching for your template dependencies. For example, if you were defining your templates as such: ```erb @@ -213,17 +229,17 @@ You can now just call the dependency once with a wildcard. <% # Template Dependency: recordings/threads/events/* %> ``` -### Remove support for `protected_attributes` gem +### Removed Support for `protected_attributes` Gem The `protected_attributes` gem is no longer supported in Rails 5. -### Remove support for `activerecord-deprecated_finders` gem +### Removed support for `activerecord-deprecated_finders` gem The `activerecord-deprecated_finders` gem is no longer supported in Rails 5. -### `ActiveSupport::TestCase` default test order is now random +### `ActiveSupport::TestCase` Default Test Order is Now Random -When tests are run in your application the default order is now `:random` +When tests are run in your application, the default order is now `:random` instead of `:sorted`. Use the following config option to set it back to `:sorted`. ```ruby @@ -233,38 +249,97 @@ Rails.application.configure do end ``` -### New config options +### `ActionController::Live` became a `Concern` + +If you include `ActionController::Live` in another module that is included in your controller, then you +should also extend the module with `ActiveSupport::Concern`. Alternatively, you can use the `self.included` hook +to include `ActionController::Live` directly to the controller once the `StreamingSupport` is included. + +This means that if your application used to have its own streaming module, the following code +would break in production mode: + +```ruby +# This is a work-around for streamed controllers performing authentication with Warden/Devise. +# See https://github.com/plataformatec/devise/issues/2332 +# Authenticating in the router is another solution as suggested in that issue +class StreamingSupport + include ActionController::Live # this won't work in production for Rails 5 + # extend ActiveSupport::Concern # unless you uncomment this line. + + def process(name) + super(name) + rescue ArgumentError => e + if e.message == 'uncaught throw :warden' + throw :warden + else + raise e + end + end +end +``` + +### New Framework Defaults -## Active Record `belongs_to` Required by Default Option +#### Active Record `belongs_to` Required by Default Option `belongs_to` will now trigger a validation error by default if the association is not present. This can be turned off per-association with `optional: true`. -This default will will be automatically configured in new applications. If existing application +This default will be automatically configured in new applications. If existing application want to add this feature it will need to be turned on in an initializer. config.active_record.belongs_to_required_by_default = true -## Allow configuration of Action Mailer queue name +#### Per-form CSRF Tokens + +Rails 5 now supports per-form CSRF tokens to mitigate against code-injection attacks with forms +created by JavaScript. With this option turned on, forms in your application will each have their +own CSRF token that is specified to the action and method for that form. + + config.action_controller.per_form_csrf_tokens = true + +#### Forgery Protection with Origin Check + +You can now configure your application to check if the HTTP `Origin` header should be checked +against the site's origin as an additional CSRF defense. Set the following in your config to +true: + + config.action_controller.forgery_protection_origin_check = true + +#### Allow Configuration of Action Mailer Queue Name The default mailer queue name is `mailers`. This configuration option allows you to globally change -the queue name. Set the following in your config. +the queue name. Set the following in your config: - config.action_mailer.deliver_later_queue_name + config.action_mailer.deliver_later_queue_name = :new_queue_name -## Support fragment caching in Action Mailer views +#### Support Fragment Caching in Action Mailer Views Set `config.action_mailer.perform_caching` in your config to determine whether your Action Mailer views should support caching. -## Configure the output of `db:structure:dump` + config.action_mailer.perform_caching = true + +#### Configure the Output of `db:structure:dump` If you're using `schema_search_path` or other PostgreSQL extentions, you can control how the schema is -dumped. Set to `:all` to generate all dumps, or `:schema_search_path` to generate from schema search path. +dumped. Set to `:all` to generate all dumps, or to `:schema_search_path` to generate from schema search path. config.active_record.dump_schemas = :all +#### Configure SSL Options to Enable HSTS with Subdomains + +Set the following in your config to enable HSTS when using subdomains: + + config.ssl_options = { hsts: { subdomains: true } } + +#### Preserve Timezone of the Receiver + +When using Ruby 2.4, you can preserve the timezone of the receiver when calling `to_time`. + + ActiveSupport.to_time_preserves_timezone = false + Upgrading from Rails 4.1 to Rails 4.2 ------------------------------------- |