aboutsummaryrefslogtreecommitdiffstats
path: root/guides
diff options
context:
space:
mode:
Diffstat (limited to 'guides')
-rw-r--r--guides/source/6_0_release_notes.md227
-rw-r--r--guides/source/action_mailbox_basics.md28
-rw-r--r--guides/source/asset_pipeline.md23
-rw-r--r--guides/source/association_basics.md16
-rw-r--r--guides/source/command_line.md27
-rw-r--r--guides/source/contributing_to_ruby_on_rails.md8
-rw-r--r--guides/source/debugging_rails_applications.md7
-rw-r--r--guides/source/documents.yaml5
-rw-r--r--guides/source/engines.md87
9 files changed, 329 insertions, 99 deletions
diff --git a/guides/source/6_0_release_notes.md b/guides/source/6_0_release_notes.md
index a4edaa1180..f1f41dc8fc 100644
--- a/guides/source/6_0_release_notes.md
+++ b/guides/source/6_0_release_notes.md
@@ -211,10 +211,237 @@ Please refer to the [Changelog][active-record] for detailed changes.
### Removals
+* Remove deprecated `#set_state` from the transaction object.
+ ([Commit](https://github.com/rails/rails/commit/6c745b0c5152a4437163a67707e02f4464493983))
+
+* Remove deprecated `#supports_statement_cache?` from the database adapters.
+ ([Commit](https://github.com/rails/rails/commit/5f3ed8784383fb4eb0f9959f31a9c28a991b7553))
+
+* Remove deprecated `#insert_fixtures` from the database adapters.
+ ([Commit](https://github.com/rails/rails/commit/400ba786e1d154448235f5f90183e48a1043eece))
+
+* Remove deprecated `ActiveRecord::ConnectionAdapters::SQLite3Adapter#valid_alter_table_type?`.
+ ([Commit](https://github.com/rails/rails/commit/45b4d5f81f0c0ca72c18d0dea4a3a7b2ecc589bf))
+
+* Remove support for passing the column name to `sum` when a block is passed.
+ ([Commit](https://github.com/rails/rails/commit/91ddb30083430622188d76eb9f29b78131df67f9))
+
+* 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.
+ ([Commit](https://github.com/rails/rails/commit/d97980a16d76ad190042b4d8578109714e9c53d0))
+
+* Remove support for delegating missing methods in a relation to private methods of the class.
+ ([Commit](https://github.com/rails/rails/commit/a7becf147afc85c354e5cfa519911a948d25fc4d))
+
+* Remove support for specifying a timestamp name for `#cache_key`.
+ ([Commit](https://github.com/rails/rails/commit/0bef23e630f62e38f20b5ae1d1d5dbfb087050ea))
+
+* Remove deprecated `ActiveRecord::Migrator.migrations_path=`.
+ ([Commit](https://github.com/rails/rails/commit/90d7842186591cae364fab3320b524e4d31a7d7d))
+
+* Remove deprecated `expand_hash_conditions_for_aggregates`.
+ ([Commit](https://github.com/rails/rails/commit/27b252d6a85e300c7236d034d55ec8e44f57a83e))
+
+
### Deprecations
+* Deprecate mismatched case-sensitivity collation comparisons for uniqueness validator.
+ ([Commit](https://github.com/rails/rails/commit/9def05385f1cfa41924bb93daa187615e88c95b9))
+
+* Deprecate using class level querying methods if the receiver scope has leaked.
+ ([Pull Request](https://github.com/rails/rails/pull/35280))
+
+* Deprecate `config.activerecord.sqlite3.represent_boolean_as_integer`.
+ ([Commit](https://github.com/rails/rails/commit/f59b08119bc0c01a00561d38279b124abc82561b))
+
+* Deprecate passing `migrations_paths` to `connection.assume_migrated_upto_version`.
+ ([Commit](https://github.com/rails/rails/commit/c1b14aded27e063ead32fa911aa53163d7cfc21a))
+
+* Deprecate `ActiveRecord::Result#to_hash` in favor of `ActiveRecord::Result#to_a`.
+ ([Commit](https://github.com/rails/rails/commit/16510d609c601aa7d466809f3073ec3313e08937))
+
+* Deprecate methods in `DatabaseLimits`: `column_name_length`, `table_name_length`,
+ `columns_per_table`, `indexes_per_table`, `columns_per_multicolumn_index`,
+ `sql_query_length`, and `joins_per_query`.
+ ([Commit](https://github.com/rails/rails/commit/e0a1235f7df0fa193c7e299a5adee88db246b44f))
+
+* Deprecate `update_attributes`/`!` in favor of `update`/`!`.
+ ([Commit](https://github.com/rails/rails/commit/5645149d3a27054450bd1130ff5715504638a5f5))
+
### Notable changes
+* Bump the minimum sqlite3 version 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.
+ ([Pull Request](https://github.com/rails/rails/pull/35768))
+
+* Add `after_save_commit` callback as shortcut for `after_commit :hook, on: [ :create, :update ]`.
+ ([Pull Request](https://github.com/rails/rails/pull/35804))
+
+* Add `ActiveRecord::Relation#extract_associated` for extracting associated records from a relation.
+ ([Pull Request](https://github.com/rails/rails/pull/35784))
+
+* Add `ActiveRecord::Relation#annotate` for adding SQL comments to ActiveRecord::Relation queries.
+ ([Pull Request](https://github.com/rails/rails/pull/35617))
+
+* Add support for setting Optimizer Hints on databases.
+ ([Pull Request](https://github.com/rails/rails/pull/35615))
+
+* Add `insert_all`/`insert_all!`/`upsert_all` methods for doing bulk inserts.
+ ([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.
+ ([Pull Request](https://github.com/rails/rails/pull/34779))
+
+* Add `reselect` method, which is a short-hand for `unscope(:select).select(fields)`.
+ ([Pull Request](https://github.com/rails/rails/pull/33611))
+
+* Add negative scopes for all enum values.
+ ([Pull Request](https://github.com/rails/rails/pull/35381))
+
+* Add `#destroy_by` and `#delete_by` for conditional removals.
+ ([Pull Request](https://github.com/rails/rails/pull/35316))
+
+* Add the ability to automatically switch database connections.
+ ([Pull Request](https://github.com/rails/rails/pull/35073))
+
+* Add the ability to prevent writes to a database for the duration of a block.
+ ([Pull Request](https://github.com/rails/rails/pull/34505))
+
+* Add an API for switching connections to support multiple databases.
+ ([Pull Request](https://github.com/rails/rails/pull/34052))
+
+* Make timestamps with precision the default for migrations.
+ ([Pull Request](https://github.com/rails/rails/pull/34970))
+
+* Support `:size` option to change text and blob size in MySQL.
+ ([Pull Request](https://github.com/rails/rails/pull/35071))
+
+* Set both the foreign key and the foreign type columns to NULL for
+ polymorphic associations on `dependent: :nullify` strategy.
+ ([Pull Request](https://github.com/rails/rails/pull/28078))
+
+* Allow a permitted instance of `ActionController::Parameters` to be passed as an
+ argument to `ActiveRecord::Relation#exists?`.
+ ([Pull Request](https://github.com/rails/rails/pull/34891))
+
+* Add support in `#where` for endless ranges introduced in Ruby 2.6.
+ ([Pull Request](https://github.com/rails/rails/pull/34906))
+
+* Make `ROW_FORMAT=DYNAMIC` a default create table option for MySQL.
+ ([Pull Request](https://github.com/rails/rails/pull/34742))
+
+* Add the ability to disable scopes generated by `ActiveRecord.enum`.
+ ([Pull Request](https://github.com/rails/rails/pull/34605/files))
+
+* Make implicit ordering configurable for a column.
+ ([Pull Request](https://github.com/rails/rails/pull/34480))
+
+* Bump the minimum PostgreSQL version to 9.3, dropping support for 9.1 and 9.2.
+ ([Pull Request](https://github.com/rails/rails/pull/34520))
+
+* Make the values of an enum frozen, raising an error when attempting to modify them.
+ ([Pull Request](https://github.com/rails/rails/pull/34517))
+
+* Make the SQL of `ActiveRecord::StatementInvalid` errors its own error property
+ and include SQL binds as a separate error property.
+ ([Pull Request](https://github.com/rails/rails/pull/34468))
+
+* Add an `:if_not_exists` option to `create_table`.
+ ([Pull Request](https://github.com/rails/rails/pull/31382))
+
+* Add support for multiple databases to `rails db:schema:cache:dump`
+ and `rails db:schema:cache:clear`.
+ ([Pull Request](https://github.com/rails/rails/pull/34181))
+
+* Add support for hash and url configs in database hash of `ActiveRecord::Base.connected_to`.
+ ([Pull Request](https://github.com/rails/rails/pull/34196))
+
+* Add support for default expressions and expression indexes for MySQL.
+ ([Pull Request](https://github.com/rails/rails/pull/34307))
+
+* Add an `index` option for `change_table` migration helpers.
+ ([Pull Request](https://github.com/rails/rails/pull/23593))
+
+* Fix `transaction` reverting for migrations. Previously, commands inside of a `transaction`
+ in a reverted migration ran uninverted. This change fixes that.
+ ([Pull Request](https://github.com/rails/rails/pull/31604))
+
+* Allow `ActiveRecord::Base.configurations=` to be set with a symbolized hash.
+ ([Pull Request](https://github.com/rails/rails/pull/33968))
+
+* Fix the counter cache to only update if the record is actually saved.
+ ([Pull Request](https://github.com/rails/rails/pull/33913))
+
+* Add expression indexes support for the SQLite adapter.
+ ([Pull Request](https://github.com/rails/rails/pull/33874))
+
+* Allow subclasses to redefine autosave callbacks for associated records.
+ ([Pull Request](https://github.com/rails/rails/pull/33378))
+
+* Bump the minimum MySQL version to 5.5.8.
+ ([Pull Request](https://github.com/rails/rails/pull/33853))
+
+* Use the utf8mb4 character set by default in MySQL.
+ ([Pull Request](https://github.com/rails/rails/pull/33608))
+
+* Add the ability to filter out sensitive data in `#inspect`
+ ([Pull Request](https://github.com/rails/rails/pull/33756), [Pull Request](https://github.com/rails/rails/pull/34208))
+
+* Change `ActiveRecord::Base.configurations` to return an object instead of a hash.
+ ([Pull Request](https://github.com/rails/rails/pull/33637))
+
+* Add database configuration to disable advisory locks.
+ ([Pull Request](https://github.com/rails/rails/pull/33691))
+
+* Update SQLite3 adapter `alter_table` method to restore foreign keys.
+ ([Pull Request](https://github.com/rails/rails/pull/33585))
+
+* 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.
+ ([Pull Request](https://github.com/rails/rails/pull/33280))
+
+* Fix the `touch` option to behave consistently with `Persistence#touch` method.
+ ([Pull Request](https://github.com/rails/rails/pull/33107))
+
+* Raise an exception for duplicate column definitions in Migrations.
+ ([Pull Request](https://github.com/rails/rails/pull/33029))
+
+* Bump the minimum SQLite version to 3.8.
+ ([Pull Request](https://github.com/rails/rails/pull/32923))
+
+* Fix parent records to not get saved with duplicate children records.
+ ([Pull Request](https://github.com/rails/rails/pull/32952))
+
+* Ensure `Associations::CollectionAssociation#size` and `Associations::CollectionAssociation#empty?`
+ use loaded association ids if present.
+ ([Pull Request](https://github.com/rails/rails/pull/32617))
+
+* Add support to preload associations of polymorphic associations when not all the records have the requested associations.
+ ([Commit](https://github.com/rails/rails/commit/75ef18c67c29b1b51314b6c8a963cee53394080b))
+
+* Add `touch_all` method to `ActiveRecord::Relation`.
+ ([Pull Request](https://github.com/rails/rails/pull/31513))
+
+* Add `ActiveRecord::Base.base_class?` predicate.
+ ([Pull Request](https://github.com/rails/rails/pull/32417))
+
+* Add custom prefix/suffix options to `ActiveRecord::Store.store_accessor`.
+ ([Pull Request](https://github.com/rails/rails/pull/32306))
+
+* Add `ActiveRecord::Base.create_or_find_by`/`!` to deal with the SELECT/INSERT race condition in
+ `ActiveRecord::Base.find_or_create_by`/`!` by leaning on unique constraints in the database.
+ ([Pull Request](https://github.com/rails/rails/pull/31989))
+
+* Add `Relation#pick` as short-hand for single-value plucks.
+ ([Pull Request](https://github.com/rails/rails/pull/31941))
+
Active Storage
--------------
diff --git a/guides/source/action_mailbox_basics.md b/guides/source/action_mailbox_basics.md
index c90892d456..de92401226 100644
--- a/guides/source/action_mailbox_basics.md
+++ b/guides/source/action_mailbox_basics.md
@@ -19,9 +19,9 @@ Introduction
------------
Action Mailbox routes incoming emails to controller-like mailboxes for
-processing in Rails. It ships with ingresses for Amazon SES, Mailgun, Mandrill,
-Postmark, and SendGrid. You can also handle inbound mails directly via the
-built-in Exim, Postfix, and Qmail ingresses.
+processing in Rails. It ships with ingresses for Mailgun, Mandrill, Postmark,
+and SendGrid. You can also handle inbound mails directly via the built-in Exim,
+Postfix, and Qmail ingresses.
The inbound emails are turned into `InboundEmail` records using Active Record
and feature lifecycle tracking, storage of the original email on cloud storage
@@ -43,28 +43,6 @@ $ rails db:migrate
## Configuration
-### Amazon SES
-
-Install the [`aws-sdk-sns`](https://rubygems.org/gems/aws-sdk-sns) gem:
-
-```ruby
-# Gemfile
-gem "aws-sdk-sns", ">= 1.9.0", require: false
-```
-
-Tell Action Mailbox to accept emails from SES:
-
-```ruby
-# config/environments/production.rb
-config.action_mailbox.ingress = :amazon
-```
-
-[Configure SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-notifications.html)
-to deliver emails to your application via POST requests to
-`/rails/action_mailbox/amazon/inbound_emails`. If your application lived at
-`https://example.com`, you would specify the fully-qualified URL
-`https://example.com/rails/action_mailbox/amazon/inbound_emails`.
-
### Exim
Tell Action Mailbox to accept emails from an SMTP relay:
diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md
index 454613e733..d853559440 100644
--- a/guides/source/asset_pipeline.md
+++ b/guides/source/asset_pipeline.md
@@ -33,13 +33,11 @@ passing the `--skip-sprockets` option.
rails new appname --skip-sprockets
```
-Rails automatically adds the `sass-rails`, `coffee-rails` and `uglifier`
-gems to your `Gemfile`, which are used by Sprockets for asset compression:
+Rails automatically adds the `sass-rails` gem to your `Gemfile`, which is used
+by Sprockets for asset compression:
```ruby
gem 'sass-rails'
-gem 'uglifier'
-gem 'coffee-rails'
```
Using the `--skip-sprockets` option will prevent Rails from adding
@@ -176,8 +174,7 @@ in `app/assets` are never served directly in production.
### Controller Specific Assets
-When you generate a scaffold or a controller, Rails also generates a JavaScript
-file (or CoffeeScript file if the `coffee-rails` gem is in the `Gemfile`) and a
+When you generate a scaffold or a controller, Rails also generates a
Cascading Style Sheet file (or SCSS file if `sass-rails` is in the `Gemfile`)
for that controller. Additionally, when generating a scaffold, Rails generates
the file `scaffolds.css` (or `scaffolds.scss` if `sass-rails` is in the
@@ -434,9 +431,8 @@ one file rather than many, the load time of pages can be greatly reduced because
the browser makes fewer requests. Compression also reduces file size, enabling
the browser to download them faster.
-
-For example, a new Rails application includes a default
-`app/assets/javascripts/application.js` file containing the following lines:
+For example, with a `app/assets/javascripts/application.js` file containing the
+following lines:
```js
// ...
@@ -476,8 +472,7 @@ which contains these lines:
*/
```
-Rails creates both `app/assets/javascripts/application.js` and
-`app/assets/stylesheets/application.css` regardless of whether the
+Rails create `app/assets/stylesheets/application.css` regardless of whether the
--skip-sprockets option is used when creating a new Rails application. This is
so you can easily add asset pipelining later if you like.
@@ -517,8 +512,7 @@ The file extensions used on an asset determine what preprocessing is applied.
When a controller or a scaffold is generated with the default Rails gemset, a
CoffeeScript file and a SCSS file are generated in place of a regular JavaScript
and CSS file. The example used before was a controller called "projects", which
-generated an `app/assets/javascripts/projects.coffee` and an
-`app/assets/stylesheets/projects.scss` file.
+generated an `app/assets/stylesheets/projects.scss` file.
In development mode, or if the asset pipeline is disabled, when these files are
requested they are processed by the processors provided by the `coffee-script`
@@ -1083,7 +1077,7 @@ Possible options for JavaScript compression are `:closure`, `:uglifier` and
`:yui`. These require the use of the `closure-compiler`, `uglifier` or
`yui-compressor` gems, respectively.
-The default `Gemfile` includes [uglifier](https://github.com/lautis/uglifier).
+Take the `uglifier` gem, for example.
This gem wraps [UglifyJS](https://github.com/mishoo/UglifyJS) (written for
NodeJS) in Ruby. It compresses your code by removing white space and comments,
shortening local variable names, and performing other micro-optimizations such
@@ -1230,4 +1224,3 @@ it as a preprocessor for your mime type.
```ruby
Sprockets.register_preprocessor 'text/css', AddComment
```
-
diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index 10538eff0f..a60ce7fb32 100644
--- a/guides/source/association_basics.md
+++ b/guides/source/association_basics.md
@@ -384,7 +384,7 @@ end
The corresponding migration might look like this:
```ruby
-class CreateSuppliers < ActiveRecord::Migration[5.0]
+class CreateSuppliers < ActiveRecord::Migration[5.2]
def change
create_table :suppliers do |t|
t.string :name
@@ -392,7 +392,7 @@ class CreateSuppliers < ActiveRecord::Migration[5.0]
end
create_table :accounts do |t|
- t.integer :supplier_id
+ t.bigint :supplier_id
t.string :account_number
t.timestamps
end
@@ -402,7 +402,7 @@ class CreateSuppliers < ActiveRecord::Migration[5.0]
end
```
-NOTE: Using `t.integer :supplier_id` makes the foreign key naming obvious and explicit. In current versions of Rails, you can abstract away this implementation detail by using `t.references :supplier` instead.
+NOTE: Using `t.bigint :supplier_id` makes the foreign key naming obvious and explicit. In current versions of Rails, you can abstract away this implementation detail by using `t.references :supplier` instead.
### Choosing Between `has_many :through` and `has_and_belongs_to_many`
@@ -466,11 +466,11 @@ Similarly, you can retrieve `@product.pictures`.
If you have an instance of the `Picture` model, you can get to its parent via `@picture.imageable`. To make this work, you need to declare both a foreign key column and a type column in the model that declares the polymorphic interface:
```ruby
-class CreatePictures < ActiveRecord::Migration[5.0]
+class CreatePictures < ActiveRecord::Migration[5.2]
def change
create_table :pictures do |t|
t.string :name
- t.integer :imageable_id
+ t.bigint :imageable_id
t.string :imageable_type
t.timestamps
end
@@ -619,11 +619,11 @@ end
These need to be backed up by a migration to create the `assemblies_parts` table. This table should be created without a primary key:
```ruby
-class CreateAssembliesPartsJoinTable < ActiveRecord::Migration[5.0]
+class CreateAssembliesPartsJoinTable < ActiveRecord::Migration[5.2]
def change
create_table :assemblies_parts, id: false do |t|
- t.integer :assembly_id
- t.integer :part_id
+ t.bigint :assembly_id
+ t.bigint :part_id
end
add_index :assemblies_parts, :assembly_id
diff --git a/guides/source/command_line.md b/guides/source/command_line.md
index a83724f1bb..4ad143d105 100644
--- a/guides/source/command_line.md
+++ b/guides/source/command_line.md
@@ -257,7 +257,7 @@ We will set up a simple resource called "HighScore" that will keep track of our
```bash
$ rails generate scaffold HighScore game:string score:integer
invoke active_record
- create db/migrate/20130717151933_create_high_scores.rb
+ create db/migrate/20190416145729_create_high_scores.rb
create app/models/high_score.rb
invoke test_unit
create test/models/high_score_test.rb
@@ -275,20 +275,19 @@ $ rails generate scaffold HighScore game:string score:integer
create app/views/high_scores/_form.html.erb
invoke test_unit
create test/controllers/high_scores_controller_test.rb
+ create test/system/high_scores_test.rb
invoke helper
create app/helpers/high_scores_helper.rb
+ invoke test_unit
invoke jbuilder
create app/views/high_scores/index.json.jbuilder
create app/views/high_scores/show.json.jbuilder
- invoke test_unit
- create test/system/high_scores_test.rb
+ create app/views/high_scores/_high_score.json.jbuilder
invoke assets
- invoke coffee
- create app/assets/javascripts/high_scores.coffee
invoke scss
create app/assets/stylesheets/high_scores.scss
invoke scss
- identical app/assets/stylesheets/scaffolds.scss
+ create app/assets/stylesheets/scaffolds.scss
```
The generator checks that there exist the directories for models, controllers, helpers, layouts, functional and unit tests, stylesheets, creates the views, controller, model and database migration for HighScore (creating the `high_scores` table and fields), takes care of the route for the **resource**, and new tests for everything.
@@ -481,6 +480,22 @@ lib/school.rb:
* [ 17] [FIXME]
```
+#### Tags
+
+You can add more default tags to search for by using `config.annotations.register_tags`. It receives a list of tags.
+
+```ruby
+config.annotations.register_tags("DEPRECATEME", "TESTME")
+```
+
+```bash
+$ rails notes
+app/controllers/admin/users_controller.rb:
+ * [ 20] [TODO] do A/B testing on this
+ * [ 42] [TESTME] this needs more functional tests
+ * [132] [DEPRECATEME] ensure this method is deprecated in next release
+```
+
#### Directories
You can add more default directories to search from by using `config.annotations.register_directories`. It receives a list of directory names.
diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md
index 569f52652f..f86589bdf1 100644
--- a/guides/source/contributing_to_ruby_on_rails.md
+++ b/guides/source/contributing_to_ruby_on_rails.md
@@ -247,7 +247,7 @@ Rails follows a simple set of coding style conventions:
* Two spaces, no tabs (for indentation).
* No trailing whitespace. Blank lines should not have any spaces.
-* Indent after private/protected.
+* Indent and no blank line after private/protected.
* Use Ruby >= 1.9 syntax for hashes. Prefer `{ a: :b }` over `{ :a => :b }`.
* Prefer `&&`/`||` over `and`/`or`.
* Prefer class << self over self.method for class methods.
@@ -302,7 +302,7 @@ the recommended workflow with the [rails-dev-box](https://github.com/rails/rails
As a compromise, test what your code obviously affects, and if the change is
not in railties, run the whole test suite of the affected component. If all
tests are passing, that's enough to propose your contribution. We have
-[Travis CI](https://travis-ci.org/rails/rails) as a safety net for catching
+[Buildkite](https://buildkite.com/rails/rails) as a safety net for catching
unexpected breakages elsewhere.
#### Entire Rails:
@@ -418,7 +418,7 @@ To run a single test against all adapters, use:
$ bundle exec rake TEST=test/cases/associations/has_many_associations_test.rb
```
-You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` also. See the file `activerecord/RUNNING_UNIT_TESTS.rdoc` for information on running more targeted database tests, or the file `ci/travis.rb` for the test suite run by the continuous integration server.
+You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` also. See the file `activerecord/RUNNING_UNIT_TESTS.rdoc` for information on running more targeted database tests.
### Warnings
@@ -677,7 +677,7 @@ $ git apply ~/my_changes.patch
This works well for simple changes. However, if your changes are complicated or if the code in master has deviated significantly from your target branch, it might require more work on your part. The difficulty of a backport varies greatly from case to case, and sometimes it is simply not worth the effort.
-Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the Ruby versions listed in `.travis.yml` before submitting your pull request.
+Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the oldest Ruby version permitted by the target branch's `rails.gemspec` before submitting your pull request.
And then... think about your next contribution!
diff --git a/guides/source/debugging_rails_applications.md b/guides/source/debugging_rails_applications.md
index 77513c3a84..170c22905b 100644
--- a/guides/source/debugging_rails_applications.md
+++ b/guides/source/debugging_rails_applications.md
@@ -962,15 +962,8 @@ Plugins for Debugging
There are some Rails plugins to help you to find errors and debug your
application. Here is a list of useful plugins for debugging:
-* [Footnotes](https://github.com/josevalim/rails-footnotes) Every Rails page has
-footnotes that give request information and link back to your source via
-TextMate.
* [Query Trace](https://github.com/ruckus/active-record-query-trace/tree/master) Adds query
origin tracing to your logs.
-* [Query Reviewer](https://github.com/nesquena/query_reviewer) This Rails plugin
-not only runs "EXPLAIN" before each of your select queries in development, but
-provides a small DIV in the rendered output of each page with the summary of
-warnings for each query that it analyzed.
* [Exception Notifier](https://github.com/smartinez87/exception_notification/tree/master)
Provides a mailer object and a default set of templates for sending email
notifications when errors occur in a Rails application.
diff --git a/guides/source/documents.yaml b/guides/source/documents.yaml
index 25e4fdb4e6..1e67b2bce7 100644
--- a/guides/source/documents.yaml
+++ b/guides/source/documents.yaml
@@ -155,6 +155,11 @@
name: Using Rails for API-only Applications
url: api_app.html
description: This guide explains how to effectively use Rails to develop a JSON API application.
+ -
+ name: Active Record and PostgreSQL
+ work_in_progress: true
+ url: active_record_postgresql.html
+ description: This guide covers PostgreSQL specific usage of Active Record.
-
name: Extending Rails
diff --git a/guides/source/engines.md b/guides/source/engines.md
index 0b17137270..3031c62928 100644
--- a/guides/source/engines.md
+++ b/guides/source/engines.md
@@ -217,10 +217,8 @@ important parts about namespacing, and is discussed later in the
#### `app` Directory
Inside the `app` directory are the standard `assets`, `controllers`, `helpers`,
-`mailers`, `models` and `views` directories that you should be familiar with
-from an application. The `helpers`, `mailers` and `models` directories are
-empty, so they aren't described in this section. We'll look more into models in
-a future section, when we're writing the engine.
+`jobs`, `mailers`, `models`, and `views` directories that you should be familiar with
+from an application. We'll look more into models in a future section, when we're writing the engine.
Within the `app/assets` directory, there are the `images`, `javascripts` and
`stylesheets` directories which, again, you should be familiar with due to their
@@ -261,6 +259,30 @@ WARNING: Don't use `require` because it will break the automatic reloading of cl
in the development environment - using `require_dependency` ensures that classes are
loaded and unloaded in the correct manner.
+Within the `app/helpers` directory there is a `blorgh` directory that
+contains a file called `application_helper.rb`. This file will provide any
+common functionality for the helpers of the engine. The `blorgh` directory
+is where the other helpers for the engine will go. By placing them within
+this namespaced directory, you prevent them from possibly clashing with
+identically-named helpers within other engines or even within the
+application.
+
+Within the `app/jobs` directory there is a `blorgh` directory that
+contains a file called `application_job.rb`. This file will provide any
+common functionality for the jobs of the engine. The `blorgh` directory
+is where the other jobs for the engine will go. By placing them within
+this namespaced directory, you prevent them from possibly clashing with
+identically-named jobs within other engines or even within the
+application.
+
+Within the `app/mailers` directory there is a `blorgh` directory that
+contains a file called `application_mailer.rb`. This file will provide any
+common functionality for the mailers of the engine. The `blorgh` directory
+is where the other mailers for the engine will go. By placing them within
+this namespaced directory, you prevent them from possibly clashing with
+identically-named mailers within other engines or even within the
+application.
+
Lastly, the `app/views` directory contains a `layouts` folder, which contains a
file at `blorgh/application.html.erb`. This file allows you to specify a layout
for the engine. If this engine is to be used as a stand-alone engine, then you
@@ -347,14 +369,11 @@ create app/views/blorgh/articles/new.html.erb
create app/views/blorgh/articles/_form.html.erb
invoke test_unit
create test/controllers/blorgh/articles_controller_test.rb
+create test/system/blorgh/articles_test.rb
invoke helper
create app/helpers/blorgh/articles_helper.rb
-invoke test_unit
-create test/application_system_test_case.rb
-create test/system/articles_test.rb
+invoke test_unit
invoke assets
-invoke js
-create app/assets/javascripts/blorgh/articles.js
invoke css
create app/assets/stylesheets/blorgh/articles.css
invoke css
@@ -394,9 +413,8 @@ be isolated from those routes that are within the application. The
Next, the `scaffold_controller` generator is invoked, generating a controller
called `Blorgh::ArticlesController` (at
`app/controllers/blorgh/articles_controller.rb`) and its related views at
-`app/views/blorgh/articles`. This generator also generates a test for the
-controller (`test/controllers/blorgh/articles_controller_test.rb`) and a helper
-(`app/helpers/blorgh/articles_helper.rb`).
+`app/views/blorgh/articles`. This generator also generates tests for the
+controller (`test/controllers/blorgh/articles_controller_test.rb` and `test/system/blorgh/articles_test.rb`) and a helper (`app/helpers/blorgh/articles_helper.rb`).
Everything this generator has created is neatly namespaced. The controller's
class is defined within the `Blorgh` module:
@@ -425,10 +443,7 @@ end
This helps prevent conflicts with any other engine or application that may have
an article resource as well.
-Finally, the assets for this resource are generated in two files:
-`app/assets/javascripts/blorgh/articles.js` and
-`app/assets/stylesheets/blorgh/articles.css`. You'll see how to use these a little
-later.
+Finally, the assets for this resource are generated in one file: `app/assets/stylesheets/blorgh/articles.css`. You'll see how to use these a little later.
You can see what the engine has so far by running `rails db:migrate` at the root
of our engine to run the migration generated by the scaffold generator, and then
@@ -579,9 +594,8 @@ invoke test_unit
create test/controllers/blorgh/comments_controller_test.rb
invoke helper
create app/helpers/blorgh/comments_helper.rb
+invoke test_unit
invoke assets
-invoke js
-create app/assets/javascripts/blorgh/comments.js
invoke css
create app/assets/stylesheets/blorgh/comments.css
```
@@ -1137,10 +1151,11 @@ end
```
```ruby
-# Blorgh/app/models/article.rb
-
-class Article < ApplicationRecord
- has_many :comments
+# Blorgh/app/models/blorgh/article.rb
+module Blorgh
+ class Article < ApplicationRecord
+ has_many :comments
+ end
end
```
@@ -1158,12 +1173,13 @@ end
```
```ruby
-# Blorgh/app/models/article.rb
-
-class Article < ApplicationRecord
- has_many :comments
- def summary
- "#{title}"
+# Blorgh/app/models/blorgh/article.rb
+module Blorgh
+ class Article < ApplicationRecord
+ has_many :comments
+ def summary
+ "#{title}"
+ end
end
end
```
@@ -1195,10 +1211,11 @@ end
```
```ruby
-# Blorgh/app/models/article.rb
-
-class Article < ApplicationRecord
- include Blorgh::Concerns::Models::Article
+# Blorgh/app/models/blorgh/article.rb
+module Blorgh
+ class Article < ApplicationRecord
+ include Blorgh::Concerns::Models::Article
+ end
end
```
@@ -1401,7 +1418,7 @@ s.add_development_dependency "moo"
Both kinds of dependencies will be installed when `bundle install` is run inside
of the application. The development dependencies for the gem will only be used
-when the tests for the engine are running.
+when the development and tests for the engine are running.
Note that if you want to immediately require dependencies when the engine is
required, you should require them before the engine's initialization. For
@@ -1536,4 +1553,6 @@ These are the available configuration hooks. They do not hook into any particula
### Example
-`config.before_configuration { puts 'I am called before any initializers' }`
+```ruby
+config.before_configuration { puts 'I am called before any initializers' }
+```
generated by cgit v1.2.3 (git 2.25.1) at 2024-10-15 21:02:20 +0000