Merge pull request rails#49888 from p8/guides/ar-callbacks-ordering

Expand the transaction callback ordering in guides [ci-skip]

Author: p8

activerecord/lib/active_record/callbacks.rb

@@ -241,8 +241,8 @@ module ActiveRecord
   #
   #   config.active_record.run_after_transaction_callbacks_in_order_defined = false
   #
-  # If +true+ (the default from \Rails 7.1), callbacks are executed in the order they
-  # are defined, just like the example above. If +false+, the order is reversed, so
+  # When set to +true+ (the default from \Rails 7.1), callbacks are executed in the order they
+  # are defined, just like the example above. When set to +false+, the order is reversed, so
   # +do_something_else+ is executed before +log_children+.
   #
   # == \Transactions

guides/source/active_record_callbacks.md

@@ -610,7 +610,9 @@ User was saved to database
 
 ### Transactional Callback Ordering
 
-When defining multiple transactional `after_` callbacks (`after_commit`, `after_rollback`, etc), the order will be reversed from when they are defined.
+By default, callbacks will run in the order they are defined. However, when
+defining multiple transactional `after_` callbacks (`after_commit`,
+`after_rollback`, etc), the order could be reversed from when they are defined.
 
 ```ruby
 class User < ActiveRecord::Base
@@ -621,6 +623,15 @@ end
 
 NOTE: This applies to all `after_*_commit` variations too, such as `after_destroy_commit`.
 
+This order can be set via configuration:
+
+```ruby
+config.active_record.run_after_transaction_callbacks_in_order_defined = false
+```
+
+When set to `true` (the default from Rails 7.1), callbacks are executed in the order they
+are defined. When set to `false`, the order is reversed, just like in the example above.
+
 [`after_create_commit`]: https://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html#method-i-after_create_commit
 [`after_destroy_commit`]: https://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html#method-i-after_destroy_commit
 [`after_save_commit`]: https://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html#method-i-after_save_commit

guides/source/configuring.md

@@ -1392,7 +1392,7 @@ The default value depends on the `config.load_defaults` target version:
 
 #### `config.active_record.run_after_transaction_callbacks_in_order_defined`
 
-If true, `after_commit` callbacks are executed in the order they are defined in a model. If false, they are executed in reverse order.
+When `true`, `after_commit` callbacks are executed in the order they are defined in a model. When `false`, they are executed in reverse order.
 
 All other callbacks are always executed in the order they are defined in a model (unless you use `prepend: true`).