diff options
Diffstat (limited to 'guides')
| -rw-r--r-- | guides/CHANGELOG.md | 5 | ||||
| -rw-r--r-- | guides/bug_report_templates/action_controller_gem.rb | 2 | ||||
| -rw-r--r-- | guides/bug_report_templates/active_job_gem.rb | 2 | ||||
| -rw-r--r-- | guides/bug_report_templates/active_record_gem.rb | 2 | ||||
| -rw-r--r-- | guides/bug_report_templates/active_record_migrations_gem.rb | 4 | ||||
| -rw-r--r-- | guides/bug_report_templates/active_record_migrations_master.rb | 2 | ||||
| -rw-r--r-- | guides/bug_report_templates/generic_gem.rb | 3 | ||||
| -rw-r--r-- | guides/source/active_job_basics.md | 31 | ||||
| -rw-r--r-- | guides/source/active_record_callbacks.md | 2 | ||||
| -rw-r--r-- | guides/source/active_storage_overview.md | 26 | ||||
| -rw-r--r-- | guides/source/active_support_core_extensions.md | 73 | ||||
| -rw-r--r-- | guides/source/caching_with_rails.md | 11 | ||||
| -rw-r--r-- | guides/source/command_line.md | 10 | ||||
| -rw-r--r-- | guides/source/getting_started.md | 4 | ||||
| -rw-r--r-- | guides/source/testing.md | 83 | ||||
| -rw-r--r-- | guides/source/upgrading_ruby_on_rails.md | 1 |
16 files changed, 165 insertions, 96 deletions
diff --git a/guides/CHANGELOG.md b/guides/CHANGELOG.md index 64e8b51817..21b4ed4b9f 100644 --- a/guides/CHANGELOG.md +++ b/guides/CHANGELOG.md @@ -1,3 +1,8 @@ +## Rails 6.0.0.alpha (Unreleased) ## + +* Rails 6 requires Ruby 2.4.1 or newer. + + *Jeremy Daer* Please check [5-2-stable](https://github.com/rails/rails/blob/5-2-stable/guides/CHANGELOG.md) for previous changes. diff --git a/guides/bug_report_templates/action_controller_gem.rb b/guides/bug_report_templates/action_controller_gem.rb index 557b1d7bef..7fc85e636a 100644 --- a/guides/bug_report_templates/action_controller_gem.rb +++ b/guides/bug_report_templates/action_controller_gem.rb @@ -13,7 +13,7 @@ gemfile(true) do git_source(:github) { |repo| "https://github.com/#{repo}.git" } # Activate the gem you are reporting the issue against. - gem "rails", "5.1.0" + gem "rails", "5.2.0.rc1" end require "rack/test" diff --git a/guides/bug_report_templates/active_job_gem.rb b/guides/bug_report_templates/active_job_gem.rb index 013d1f8602..6b30a7d446 100644 --- a/guides/bug_report_templates/active_job_gem.rb +++ b/guides/bug_report_templates/active_job_gem.rb @@ -13,7 +13,7 @@ gemfile(true) do git_source(:github) { |repo| "https://github.com/#{repo}.git" } # Activate the gem you are reporting the issue against. - gem "activejob", "5.1.0" + gem "activejob", "5.2.0.rc1" end require "minitest/autorun" diff --git a/guides/bug_report_templates/active_record_gem.rb b/guides/bug_report_templates/active_record_gem.rb index 921917fbe9..fabc2a2382 100644 --- a/guides/bug_report_templates/active_record_gem.rb +++ b/guides/bug_report_templates/active_record_gem.rb @@ -13,7 +13,7 @@ gemfile(true) do git_source(:github) { |repo| "https://github.com/#{repo}.git" } # Activate the gem you are reporting the issue against. - gem "activerecord", "5.1.0" + gem "activerecord", "5.2.0.rc1" gem "sqlite3" end diff --git a/guides/bug_report_templates/active_record_migrations_gem.rb b/guides/bug_report_templates/active_record_migrations_gem.rb index 9002b8f428..ca9987f956 100644 --- a/guides/bug_report_templates/active_record_migrations_gem.rb +++ b/guides/bug_report_templates/active_record_migrations_gem.rb @@ -13,7 +13,7 @@ gemfile(true) do git_source(:github) { |repo| "https://github.com/#{repo}.git" } # Activate the gem you are reporting the issue against. - gem "activerecord", "5.1.0" + gem "activerecord", "5.2.0.rc1" gem "sqlite3" end @@ -37,7 +37,7 @@ end class Payment < ActiveRecord::Base end -class ChangeAmountToAddScale < ActiveRecord::Migration[5.1] +class ChangeAmountToAddScale < ActiveRecord::Migration[5.2] def change reversible do |dir| dir.up do diff --git a/guides/bug_report_templates/active_record_migrations_master.rb b/guides/bug_report_templates/active_record_migrations_master.rb index 194b093ac3..715dca98ba 100644 --- a/guides/bug_report_templates/active_record_migrations_master.rb +++ b/guides/bug_report_templates/active_record_migrations_master.rb @@ -36,7 +36,7 @@ end class Payment < ActiveRecord::Base end -class ChangeAmountToAddScale < ActiveRecord::Migration[5.2] +class ChangeAmountToAddScale < ActiveRecord::Migration[6.0] def change reversible do |dir| dir.up do diff --git a/guides/bug_report_templates/generic_gem.rb b/guides/bug_report_templates/generic_gem.rb index 60e8322c2a..7a55d7c660 100644 --- a/guides/bug_report_templates/generic_gem.rb +++ b/guides/bug_report_templates/generic_gem.rb @@ -13,9 +13,10 @@ gemfile(true) do git_source(:github) { |repo| "https://github.com/#{repo}.git" } # Activate the gem you are reporting the issue against. - gem "activesupport", "5.1.0" + gem "activesupport", "5.2.0.rc1" end +require "active_support" require "active_support/core_ext/object/blank" require "minitest/autorun" diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md index 9b738e8cdd..97d98efba0 100644 --- a/guides/source/active_job_basics.md +++ b/guides/source/active_job_basics.md @@ -276,7 +276,7 @@ class GuestsCleanupJob < ApplicationJob end private - def around_cleanup(job) + def around_cleanup # Do something before perform yield # Do something after perform @@ -344,14 +344,14 @@ Supported types for arguments ActiveJob supports the following types of arguments by default: - - Basic types (`NilClass`, `String`, `Integer`, `Fixnum`, `Bignum`, `Float`, `BigDecimal`, `TrueClass`, `FalseClass`) + - Basic types (`NilClass`, `String`, `Integer`, `Float`, `BigDecimal`, `TrueClass`, `FalseClass`) - `Symbol` - - `ActiveSupport::Duration` - `Date` - `Time` - `DateTime` - `ActiveSupport::TimeWithZone` - - `Hash`. Keys should be of `String` or `Symbol` type + - `ActiveSupport::Duration` + - `Hash` (Keys should be of `String` or `Symbol` type) - `ActiveSupport::HashWithIndifferentAccess` - `Array` @@ -385,39 +385,38 @@ by default has been mixed into Active Record classes. ### Serializers -You can extend list of supported types for arguments. You just need to define your own serializer. +You can extend the list of supported argument types. You just need to define your own serializer: ```ruby class MoneySerializer < ActiveJob::Serializers::ObjectSerializer - # Check if this object should be serialized using this serializer. + # Checks if an argument should be serialized by this serializer. def serialize?(argument) argument.is_a? Money end - # Convert an object to a simpler representative using supported object types. + # Converts an object to a simpler representative using supported object types. # The recommended representative is a Hash with a specific key. Keys can be of basic types only. - # You should call `super` to add the custom serializer type to the hash - def serialize(object) + # You should call `super` to add the custom serializer type to the hash. + def serialize(money) super( - "cents" => object.cents, - "currency" => object.currency + "amount" => money.amount, + "currency" => money.currency ) end - # Convert serialized value into a proper object + # Converts serialized value into a proper object. def deserialize(hash) - Money.new hash["cents"], hash["currency"] + Money.new(hash["amount"], hash["currency"]) end end ``` -And now you just need to add this serializer to a list: +and add this serializer to the list: ```ruby -Rails.application.config.active_job.custom_serializers << MySpecialSerializer +Rails.application.config.active_job.custom_serializers << MoneySerializer ``` - Exceptions ---------- diff --git a/guides/source/active_record_callbacks.md b/guides/source/active_record_callbacks.md index 630dafe632..4f54b4c206 100644 --- a/guides/source/active_record_callbacks.md +++ b/guides/source/active_record_callbacks.md @@ -264,7 +264,7 @@ The whole callback chain is wrapped in a transaction. If any callback raises an throw :abort ``` -WARNING. Any exception that is not `ActiveRecord::Rollback` or `ActiveRecord::RecordInvalid` will be re-raised by Rails after the callback chain is halted. Raising an exception other than `ActiveRecord::Rollback` or `ActiveRecord::RecordInvalid` may break code that does not expect methods like `save` and `update_attributes` (which normally try to return `true` or `false`) to raise an exception. +WARNING. Any exception that is not `ActiveRecord::Rollback` or `ActiveRecord::RecordInvalid` will be re-raised by Rails after the callback chain is halted. Raising an exception other than `ActiveRecord::Rollback` or `ActiveRecord::RecordInvalid` may break code that does not expect methods like `save` and `update` (which normally try to return `true` or `false`) to raise an exception. Relational Callbacks -------------------- diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md index 97c56dfd93..a7cb14c52a 100644 --- a/guides/source/active_storage_overview.md +++ b/guides/source/active_storage_overview.md @@ -121,6 +121,8 @@ Add the [`aws-sdk-s3`](https://github.com/aws/aws-sdk-ruby) gem to your `Gemfile gem "aws-sdk-s3", require: false ``` +NOTE: The core features of Active Storage require the following permissions: `s3:ListBucket`, `s3:PutObject`, `s3:GetObject`, and `s3:DeleteObject`. If you have additional upload options configured such as setting ACLs then additional permissions may be required. + ### Microsoft Azure Storage Service Declare an Azure Storage service in `config/storage.yml`: @@ -556,6 +558,30 @@ config.active_job.queue_adapter = :inline config.active_storage.service = :local_test ``` +Discarding Files Stored During Integration Tests +------------------------------------------- + +Similarly to System Tests, files uploaded during Integration Tests will not be +automatically cleaned up. If you want to clear the files, you can do it in an +`after_teardown` callback. Doing it here ensures that all connections created +during the test are complete and you won't receive an error from Active Storage +saying it can't find a file. + +```ruby +module ActionDispatch + class IntegrationTest + def remove_uploaded_files + FileUtils.rm_rf(Rails.root.join('tmp', 'storage')) + end + + def after_teardown + super + remove_uploaded_files + end + end +end +``` + Implementing Support for Other Cloud Services --------------------------------------------- diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index 6c980fb0e9..73b24b900a 100644 --- a/guides/source/active_support_core_extensions.md +++ b/guides/source/active_support_core_extensions.md @@ -135,16 +135,14 @@ NOTE: Defined in `active_support/core_ext/object/blank.rb`. ### `duplicable?` -In Ruby 2.4 most objects can be duplicated via `dup` or `clone` except -methods and certain numbers. Though Ruby 2.2 and 2.3 can't duplicate `nil`, -`false`, `true`, and symbols as well as instances `Float`, `Fixnum`, -and `Bignum` instances. +As of Ruby 2.5, most objects can be duplicated via `dup` or `clone`: ```ruby "foo".dup # => "foo" "".dup # => "" -1.method(:+).dup # => TypeError: allocator undefined for Method -Complex(0).dup # => TypeError: can't copy Complex +Rational(1).dup # => (1/1) +Complex(0).dup # => (0+0i) +1.method(:+).dup # => TypeError (allocator undefined for Method) ``` Active Support provides `duplicable?` to query an object about this: @@ -152,35 +150,18 @@ Active Support provides `duplicable?` to query an object about this: ```ruby "foo".duplicable? # => true "".duplicable? # => true -Rational(1).duplicable? # => false -Complex(1).duplicable? # => false +Rational(1).duplicable? # => true +Complex(1).duplicable? # => true 1.method(:+).duplicable? # => false ``` -`duplicable?` matches Ruby's `dup` according to the Ruby version. - -So in 2.4: +`duplicable?` matches the current Ruby version's `dup` behavior, +so results will vary according the version of Ruby you're using. +In Ruby 2.4, for example, Complex and Rational are not duplicable: ```ruby -nil.dup # => nil -:my_symbol.dup # => :my_symbol -1.dup # => 1 - -nil.duplicable? # => true -:my_symbol.duplicable? # => true -1.duplicable? # => true -``` - -Whereas in 2.2 and 2.3: - -```ruby -nil.dup # => TypeError: can't dup NilClass -:my_symbol.dup # => TypeError: can't dup Symbol -1.dup # => TypeError: can't dup Fixnum - -nil.duplicable? # => false -:my_symbol.duplicable? # => false -1.duplicable? # => false +Rational(1).duplicable? # => false +Complex(1).duplicable? # => false ``` WARNING: Any class can disallow duplication by removing `dup` and `clone` or raising exceptions from them. Thus only `rescue` can tell whether a given arbitrary object is duplicable. `duplicable?` depends on the hard-coded list above, but it is much faster than `rescue`. Use it only if you know the hard-coded list is enough in your use case. @@ -2776,20 +2757,6 @@ Active Record does not accept unknown options when building associations, for ex NOTE: Defined in `active_support/core_ext/hash/keys.rb`. -### Working with Values - -#### `transform_values` && `transform_values!` - -The method `transform_values` accepts a block and returns a hash that has applied the block operations to each of the values in the receiver. - -```ruby -{ nil => nil, 1 => 1, :x => :a }.transform_values { |value| value.to_s.upcase } -# => {nil=>"", 1=>"1", :x=>"A"} -``` -There's also the bang variant `transform_values!` that applies the block operations to values in the very receiver. - -NOTE: Defined in `active_support/core_ext/hash/transform_values.rb`. - ### Slicing Ruby has built-in support for taking slices out of strings and arrays. Active Support extends slicing to hashes: @@ -2890,24 +2857,6 @@ end NOTE: Defined in `active_support/core_ext/regexp.rb`. -### `match?` - -Rails implements `Regexp#match?` for Ruby versions prior to 2.4: - -```ruby -/oo/.match?('foo') # => true -/oo/.match?('bar') # => false -/oo/.match?('foo', 1) # => true -``` - -The backport has the same interface and lack of side-effects in the caller like -not setting `$1` and friends, but it does not have the speed benefits. Its -purpose is to be able to write 2.4 compatible code. Rails itself uses this -predicate internally for example. - -Active Support defines `Regexp#match?` only if not present, so code running -under 2.4 or later does run the original one and gets the performance boost. - Extensions to `Range` --------------------- diff --git a/guides/source/caching_with_rails.md b/guides/source/caching_with_rails.md index cd9f4b4a68..5dde6f34fa 100644 --- a/guides/source/caching_with_rails.md +++ b/guides/source/caching_with_rails.md @@ -465,6 +465,10 @@ is often faster than waiting more than a second to retrieve it. Both read and write timeouts default to 1 second, but may be set lower if your network is consistently low latency. +By default, the cache store will not attempt to reconnect to Redis if the +connection fails during a request. If you experience frequent disconnects you +may wish to enable reconnect attempts. + Cache reads and writes never raise exceptions. They just return `nil` instead, behaving as if there was nothing in the cache. To gauge whether your cache is hitting exceptions, you may provide an `error_handler` to report to an @@ -480,9 +484,10 @@ like this: cache_servers = %w[ "redis://cache-01:6379/0", "redis://cache-02:6379/0", … ], config.cache_store = :redis_cache_store, url: cache_servers, - connect_timeout: 30, # Defaults to 20 seconds - read_timeout: 0.2, # Defaults to 1 second - write_timeout: 0.2, # Defaults to 1 second + connect_timeout: 30, # Defaults to 20 seconds + read_timeout: 0.2, # Defaults to 1 second + write_timeout: 0.2, # Defaults to 1 second + reconnect_attempts: 1, # Defaults to 0 error_handler: -> (method:, returning:, exception:) { # Report errors to Sentry as warnings diff --git a/guides/source/command_line.md b/guides/source/command_line.md index 648645af7c..b41e8bbec6 100644 --- a/guides/source/command_line.md +++ b/guides/source/command_line.md @@ -431,16 +431,16 @@ INFO: You can also use `bin/rails -T` to get the list of tasks. ```bash $ bin/rails about About your application's environment -Rails version 5.1.0 -Ruby version 2.2.2 (x86_64-linux) -RubyGems version 2.4.6 -Rack version 2.0.1 +Rails version 6.0.0 +Ruby version 2.5.0 (x86_64-linux) +RubyGems version 2.7.3 +Rack version 2.0.4 JavaScript Runtime Node.js (V8) Middleware: Rack::Sendfile, ActionDispatch::Static, ActionDispatch::Executor, ActiveSupport::Cache::Strategy::LocalCache::Middleware, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, ActionDispatch::RemoteIp, Sprockets::Rails::QuietAssets, Rails::Rack::Logger, ActionDispatch::ShowExceptions, WebConsole::Middleware, ActionDispatch::DebugExceptions, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActionDispatch::Cookies, ActionDispatch::Session::CookieStore, ActionDispatch::Flash, Rack::Head, Rack::ConditionalGet, Rack::ETag Application root /home/foobar/commandsapp Environment development Database adapter sqlite3 -Database schema version 20110805173523 +Database schema version 20180205173523 ``` ### `assets` diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index ad587d6117..f545b90103 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -87,10 +87,10 @@ current version of Ruby installed: ```bash $ ruby -v -ruby 2.3.1p112 +ruby 2.5.0 ``` -Rails requires Ruby version 2.2.2 or later. If the version number returned is +Rails requires Ruby version 2.4.1 or later. If the version number returned is less than that number, you'll need to install a fresh copy of Ruby. TIP: A number of tools exist to help you quickly install Ruby and Ruby diff --git a/guides/source/testing.md b/guides/source/testing.md index af6127f4a5..b9b310cbba 100644 --- a/guides/source/testing.md +++ b/guides/source/testing.md @@ -462,6 +462,89 @@ Rails options: -c, --[no-]color Enable color in the output ``` +Parallel Testing +---------------- + +Parallel testing allows you to parallelize your test suite. While forking processes is the +default method, threading is supported as well. Running tests in parallel reduces the time it +takes your entire test suite to run. + +### Parallel testing with processes + +The default parallelization method is to fork processes using Ruby's DRb system. The processes +are forked based on the number of workers provided. The default is 2, but can be changed by the +number passed to the parallelize method. Active Record automatically handles creating and +migrating a new database for each worker to use. + +To enable parallelization add the following to your `test_helper.rb`: + +``` +class ActiveSupport::TestCase + parallelize(workers: 2) +end +``` + +The number of workers passed is the number of times the process will be forked. You may want to +parallelize your local test suite differently from your CI, so an environment variable is provided +to be able to easily change the number of workers a test run should use: + +``` +PARALLEL_WORKERS=15 bin/rails test +``` + +When parallelizing tests, Active Record automatically handles creating and migrating a database for each +process. The databases will be suffixed with the number corresponding to the worker. For example, if you +have 2 workers the tests will create `test-database-0` and `test-database-1` respectively. + +If the number of workers passed is 1 or fewer the processes will not be forked and the tests will not +be parallelized and the tests will use the original `test-database` database. + +Two hooks are provided, one runs when the process is forked, and one runs before the processes are closed. +These can be useful if your app uses multiple databases or perform other tasks that depend on the number of +workers. + +The `parallelize_setup` method is called right after the processes are forked. The `parallelize_teardown` metod +is called right before the processes are closed. + +``` +class ActiveSupport::TestCase + parallelize_setup do |worker| + # setup databases + end + + parallelize_teardown do |worker| + # cleanup database + end + + parallelize(workers: 2) +end +``` + +These methods are not needed or available when using parallel testing with threads. + +### Parallel testing with threads + +If you prefer using threads or are using JRuby, a threaded parallelization option is provided. The threaded +parallelizer is backed by Minitest's `Parallel::Executor`. + +To change the parallelization method to use threads over forks put the following in your `test_helper.rb` + +``` +class ActiveSupport::TestCase + parallelize(workers: 2, with: :threads) +end +``` + +Rails applications generated from JRuby will automatically include the `with: :threads` option. + +The number of workers passed to `parallelize` determines the number of threads the tests will use. You may +want to parallelize your local test suite differently from your CI, so an environment variable is provided +to be able to easily change the number of workers a test run should use: + +``` +PARALLEL_WORKERS=15 bin/rails test +``` + The Test Database ----------------- diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index 51b284ff12..ff7ccfd47d 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -35,6 +35,7 @@ You can find a list of all released Rails versions [here](https://rubygems.org/g Rails generally stays close to the latest released Ruby version when it's released: +* Rails 6 requires Ruby 2.4.1 or newer. * Rails 5 requires Ruby 2.2.2 or newer. * Rails 4 prefers Ruby 2.0 and requires 1.9.3 or newer. * Rails 3.2.x is the last branch to support Ruby 1.8.7. |