diff options
-rw-r--r-- | actioncable/README.md | 68 | ||||
-rw-r--r-- | guides/source/5_0_release_notes.md | 6 | ||||
-rw-r--r-- | guides/source/upgrading_ruby_on_rails.md | 139 |
3 files changed, 207 insertions, 6 deletions
diff --git a/actioncable/README.md b/actioncable/README.md index 50523d4b0f..28e2602cbf 100644 --- a/actioncable/README.md +++ b/actioncable/README.md @@ -458,6 +458,74 @@ with all the popular application servers -- Unicorn, Puma and Passenger. Action Cable does not work with WEBrick, because WEBrick does not support the Rack socket hijacking API. +## Frontend assets + +Action Cable's frontend assets are distributed through two channels: the +official gem and npm package, both titled `actioncable`. + +### Gem usage + +Through the `actioncable` gem, Action Cable's frontend assets are +available through the Rails Asset Pipeline. Create a `cable.js` or +`cable.coffee` file (this is automatically done for you with Rails +generators), and then simply require the assets: + +In JavaScript... + +```javascript +//= require action_cable +``` + +... and in CoffeeScript: + +```coffeescript +#= require action_cable +``` + +### npm usage + +In addition to being available through the `actioncable` gem, Action Cable's +frontend JS assets are also bundled in an officially supported npm module, +intended for usage in standalone frontend applications that communicate with a +Rails application. A common use case for this could be if you have a decoupled +frontend application written in React, Ember.js, etc. and want to add real-time +WebSocket functionality. + +### Installation + +``` +npm install actioncable --save +``` + +### Usage + +The `ActionCable` constant is available as a `require`-able module, so +you only have to require the package to gain access to the API that is +provided. + +In JavaScript... + +```javascript +ActionCable = require('actioncable') + +var cable = ActionCable.createConsumer('wss://RAILS-API-PATH.com/cable') + +cable.subscriptions.create('AppearanceChannel', { + // normal channel code goes here... +}); +``` + +and in CoffeeScript... + +```coffeescript +ActionCable = require('actioncable') + +cable = ActionCable.createConsumer('wss://RAILS-API-PATH.com/cable') + +cable.subscriptions.create 'AppearanceChannel', + # normal channel code goes here... +``` + ## License Action Cable is released under the MIT license: diff --git a/guides/source/5_0_release_notes.md b/guides/source/5_0_release_notes.md index 0ccf8c58ca..f0c7f03bf2 100644 --- a/guides/source/5_0_release_notes.md +++ b/guides/source/5_0_release_notes.md @@ -549,8 +549,10 @@ Please refer to the [Changelog][active-record] for detailed changes. [activemodel-serializers-xml](https://github.com/rails/activemodel-serializers-xml) gem. ([Pull Request](https://github.com/rails/rails/pull/21161)) -* Removed support for the legacy `mysql` database adapter from core. It will - live on in a separate gem for now, but most users should just use `mysql2`. +* Removed support for the legacy `mysql` database adapter from core. Most users should + be able to use `mysql2`. It will be converted to a separate gem when when we find someone + to maintain it. ([Pull Request 1](https://github.com/rails/rails/pull/22642)], + [Pull Request 2](https://github.com/rails/rails/pull/22715)) * Removed support for the `protected_attributes` gem. ([commit](https://github.com/rails/rails/commit/f4fbc0301021f13ae05c8e941c8efc4ae351fdf9)) diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index 82080c4def..cbe46d6c0d 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -68,10 +68,12 @@ Don't forget to review the difference, to see if there were any unexpected chang Upgrading from Rails 4.2 to Rails 5.0 ------------------------------------- -### Ruby 2.2.2+ +For more information on changes made to Rails 5.0 please see the [release notes](5_0_release_notes.html). -From Ruby on Rails 5.0 onwards, Ruby 2.2.2+ is the only supported version. -Make sure you are on Ruby 2.2.2 version or greater, before you proceed. +### Ruby 2.2.2+ required + +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 @@ -119,7 +121,7 @@ See [#17227](https://github.com/rails/rails/pull/17227) for more details. ### ActiveJob jobs now inherit from ApplicationJob by default -In Rails 4.2 an ActiveJob 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 @@ -134,6 +136,135 @@ Then make sure that all your job classes inherit from it. 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 +your Gemfile. + +If you are using Rspec for testing please see the extra configuration required in the gem's +documentation. + +### 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'` +to your Gemfile. + +### Removed support for legacy MySQL + +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 + +`debugger` is not supported by Ruby 2.2 which is required by Rails 5. Use `byebug` instead. + +### Use bin/rails for running tasks and tests + +Rails 5 adds the ability to run tasks and tests through `bin/rails` instead of rake. Generally +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 + +Run `bin/rails` to see the list of commands available. + +### `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 +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` 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 prepend: true`. + +### 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. + +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 + +You can now use wildcard matching for your template dependencies. For example if you were +defining your templates as such: + +```erb +<% # Template Dependency: recordings/threads/events/subscribers_changed %> +<% # Template Dependency: recordings/threads/events/completed %> +<% # Template Dependency: recordings/threads/events/uncompleted %> +``` + +You can now just call the dependency once with a wildcard. + +```erb +<% # Template Dependency: recordings/threads/events/* %> +``` + +### Remove support for `protected_attributes` gem + +The `protected_attributes` gem is no longer supported in Rails 5. + +### Remove 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 + +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 +# config/environments/test.rb +Rails.application.configure do + config.active_support.test_order = :sorted +end +``` + +### New config options + +## 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 +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 + +The default mailer queue name is `mailers`. This configuration option allows you to globally change +the queue name. Set the following in your config. + + config.action_mailer.deliver_later_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 +should support caching. + +## 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. + + config.active_record.dump_schemas = :all + Upgrading from Rails 4.1 to Rails 4.2 ------------------------------------- |