Review and improve Action Text guide:
- More detailed installation steps
- Explain generated files a bit
- Improved examples
- More information around customizing the HTML/CSS
- Expand information about attachments
Co-authored-by: Carlos Antonio da Silva <carlosantoniodasilva@gmail.com>
Review and improve Action Mailbox guide, with some sections added/improved:
- Installation steps
- Processing Incoming Email - more of a step by step of the flow
- Mail object and it's fields
- List of Inbound Email 'status' values
- Routing and Incineration
Co-authored-by: Carlos Antonio da Silva <carlosantoniodasilva@gmail.com>
While I was reading the Debugging Rails Applications guide, this typo
threw me off and I had to re-read it to understand the intended meaning,
so it seems like it's worth fixing.
And after digging in a little more, rewording the `path` example can add
some clarity.
This paragraph tends to cause confustion with Rails developers who have just learned the correct control flow of `redirect_to` and `render`.
A phrase above it in the "Avoiding Double Render Errors" section clears up a common misunderstanding that `render` will stop execution within a controller action. That misunderstanding is further corrected with the following phrase.
> But this will _not_ stop the rest of the code in the `show` action from running
This section is often enough to get the point across for newer developers who might often be running into double render errors, but soon after the phrase which attempts the same illustration of `redirect_to`'s execution confuses the matter by using the same language as the earlier statement to mean the opposite.
> Sometimes inexperienced developers think of `redirect_to` as a sort of `goto` command, moving execution from one place to another in your Rails code. This is _not_ correct. Your code stops running and waits for a new request from the browser.
Here "Your code stops running" means that the action will run to completion and not jump to another site in controller code. This often re-confuses the concept they've just learned and undermines their understanding. By being more specific in the second phrase, we can reinforce the concept instead.
All headers in a guide get a unique `dom_id` to make anchor links work.
If a header is already present we would prefix it with the `dom_id` of
the parent node. This would not work for headers without parent nodes.
This commit simplifies the `dom_id` uniqueness by only prepending the
parent node if it exists. This can still result in duplicates at the
same level, but for these we already show a warning:
*** DUPLICATE ID: 'some_id', please make sure that there are no
headings with the same name at the same level.
Co-authored-by: Carlos Antonio da Silva <carlosantoniodasilva@gmail.com>
When set, an `ActiveRecord::InvalidMigrationTimestampError` will be raised if the timestamp
prefix for a migration is more than a day ahead of the timestamp associated with the current time.
This is done to prevent forward-dating of migration files, which can impact migration generation
and other migration commands.
It is turned off by default, but will be turned on for applications starting in Rails 7.2.
* Add ".[key]" to the abstract namespaces [ci skip]
The section "Error Message Scopes" describes how the Rails look up the
namespaces for a validation error message with code snippets.
The first code snippet shows abstract namespaces like
`errors.attributes.[attribute_name]` while the second one demonstrates
the materialized one like `errors.attributes.name.blank`.
The first code snippet lacks the validation error "key." My team member
was confused and created a translation without "key", so I think it
would be helpful to add ".[key]" to the abstract namespaces.
* Move abstract key list after :blank examples
Co-authored-by: Rafael Mendonça França <rafael@rubyonrails.org>
This field returns the amount of rows returned by the query that emitted the notification.
This metric is useful in cases where one wants to detect queries with big result sets.
Motivation / Background
---
Strict Locals support was introduced in [#45727][] and announced as part
of the [7.1 Release][]. There are several mentions across the Guides,
but support is rarely mentioned in the API documentation.
Detail
----
Mention the template short identifier (the pathname, in most cases) as
part of the `ArgumentError` message.
This commit adds two test cases to ensure support for splatting
additional arguments, and for forbidding block and positional arguments.
It also makes mention of strict locals in more places, and links to the
guides.
[#45727]: https://github.com/rails/rails/pull/45727
[7.1 Release]: https://edgeguides.rubyonrails.org/7_1_release_notes.html#allow-templates-to-set-strict-locals
The code: Book.joins(:author, :reviews)
This code will return books that have an author and at least 1
review.
English text implies it returns the book and the author:
"return all books with their author .."
Changing the text to imply it returns books with an author.
When Rake parses an argument string with no tasks, it sets the top-level
task as "default". Prior to this commit, if no default task was defined
(for example, if an app was generated with `--skip-test` and didn't
define its own default task), `Rails::Command::RakeCommand` would raise
`UnrecognizedCommandError`, preventing Rake from displaying the task
list.
This commit changes `Rails::Command::RakeCommand` to let Rake handle the
"default" task.
Fixes#50700.
Support for the new `action_dispatch.show_exceptions` values was
introduced in [e28f147][]. Alongside the change to introduce new values
(like `:all`, `:rescuable`, `:none`), the default behavior was changed
for `Rails.env.test?`.
Prior to that commit, the `test` environment's default value was `false`
(introduced in [d898a4b][]) (which corresponds to the new `:none`
setting).
The new default behavior has some unintended negative side effects that
impact the feedback loop at the core of test-driven development.
When errors are rescued and transformed into HTML pages, the context of
the cause of failure is obscured by additional layers of information.
First, this commit adds more prominent entries to the Upgrading and
Configuring guides, as well as the 7.1 Release Notes to document the
details of the configuration and its new values.
Next, this commit adds more documentation around the change in default
behavior. To start, it mentions the new value in the sections for the
affected test types: Controller, Integration, and System.
[e28f147]: e28f147329
[d898a4b]: d898a4ba42
We recently had [two][1] [PRs][2] to update these types of links, so
this commit does all of the rest (remaining links to master branches
were checked and still exist).
[1]: e76c52a939
[2]: a2ed3437e3
Provide examples for rendering objects that respond to `render_in`. Also
highlight that the object can also define a `#format` method to control
how the rendered String should be treated.
Add test coverage for both Action View's and Action Pack's support for
`render` with `:renderable` options.
It is the role of the underlying serializer to accept or reject the data
to decrypt depending on its type. This behavior mirrors what is done at
encryption, where the serializer asserts that the input is an
ActiveRecord::Encryption::Message.
This change allows for a wider variety of custom serializers, but does
not change the behavior when using the default MessageSerializer class.
Indeed, the default message serializer will raise a TypeError when
invoking JSON.parse on any non-String input. This error will subsequently
be translated into an ActiveRecord::Encryption::Errors::Encoding error
by the encryptor, which does not change the current behavior at the
encryptor level.
A new test asserts that the default MessageSerializer is able to reject
unexpected data types on its own at decryption time, just as it does at
encryption time (test already present). The test also asserts that an
exception is translated into an ActiveRecord::Encryption::Error::Encoding
error at the encryptor level.
The "English" and "Oxford Comma" sections currently have 1 or 2
sentences, which makes it difficult to justify their own top sections.
Moving the "English" section under the "Wording" section makes sense, as
we already have a "Naming" section. We can rename it to "American
English" for easier scanability.
As the "Wording" section also mentions punctuation, we can move the
"Oxford Comma" section there as well.
This provides a shortcut for setting a Content Security Policy nonce on
a stylesheet_link_tag.
Co-authored-by: AJ Esler <ajesler@users.noreply.github.com>
Closes#49818
Renames `ActionView::TestCase::Behavior::Content` to
`RenderedViewContent`, with the goal of making it more of an internal
implementation detail that's unlikely to collide with an
application-side `::Content` class.
The `RenderedView`-prefix mirrors the module's `RenderedViewsCollection`
class. Since the intention is to treat it as a private implementation
detail, `RenderedViewContent` is marked with `:nodoc:`.
Along with the rename, this commit also modifies the class inheritance,
replacing the `SimpleDelegator` superclass with `String`. [String.new][]
accepts a `String` positional argument in the same way as
`SimpleDelegator.new` accepts a delegate object positional argument.
Sharing the `String` superclass also makes it a good candidate for being
passed to [Capybara.string][] (and [Capybara::Node::Simple.new][]) like
the documentation suggests.
[Capybara.string]: https://github.com/teamcapybara/capybara/blob/3.39.2/lib/capybara.rb#L212-L242
[Capybara::Node::Simple.new]: https://github.com/teamcapybara/capybara/blob/3.39.2/lib/capybara/node/simple.rb#L23
[String.new]: https://ruby-doc.org/core/String.html#method-c-new
The issue was raised years ago at https://github.com/rails/rails/issues/27128
where everyone involved agreed that the documentation should be worked on,
only to leave it forgotten.
I believe it is still relevant as the ambiguity remains ever since.
Also, two of exceptions which have a seat in the current default
have been missing in the documentation so this commit aligns them.
One of the original goals of these checks was to validate that
configuration stays in alphabetical order, as this provides a
deterministic order for the configuration to be validated against.
However, it appears there has been a regression in that check and it has
only been validating that configurations are present. This commit
restores the ordering check and then uses `railspect configuration . -a`
to fix the configurations that ended up out of order.
Introduce Action View bug report template for contributors to reproduce
issues with failing `ActionView::TestCase` instances.
In addition to rendering ERB with the `inline:` keyword, the sample
tests also include a `Helpers` module to demonstrate how to incorporate
view helpers into the reproduction script.
I was reading the Action Mailer guide and noticed the settings and
defaults for the `:file` delivery method were poorly documented. These
docs were originally added back in #13728. #44422 added links to the
relevant sections of the Configuration guide, but did not link
`config.action_mailer.file_settings` because the Configuration guide is
actually missing that section.
I added a short section to the Configuration guide for
`config.action_mailer.file_settings` and linked to it from the Action
Mailer guide, following the style of the other delivery methods. Like
other delivery methods, the relevant options for `file_settings` come
from the allowed options of the `Mail::FileDelivery` class in the mail
gem.
Here's where Rails sets up this delivery method with the default
location:
9064735ec5/actionmailer/lib/action_mailer/delivery_methods.rb (L30-L31)
And here's where the mail gem uses the options:
10a4443b9d/lib/mail/network/delivery_methods/file_delivery.rb (L21)
- Link to Deprecation::Behavior in configuring guide
The current list of options for `config.active_support.deprecation`
was missing the newly added `:report` option. Instead of adding the
missing option and continuing to keep 4 different lists of the same
options in sync, I opted to replace the list with a link to the
options in the Behavior API docs. This had the additional advantage of
giving more information about all of the options which was not
mentioned in the Configuring guide.
- Use symbols for Behavior options
It felt to me like naming the options did not make it explicit that
those were the symbols to pass to `#behavior=`, but by adding the `:`
that becomes more clear.
- Add some API links
There were a few references to `behavior=`, but we may as well link to
the actual method.
In commit 449039a86d,
ActionDispatch::Head was replaced with Rack::Head in the
middleware. However, the documentation was not changed.
Rack::Head code behaviour is not to change HEAD into GET it is to
close the body of all HEAD requests. This commit fixes the docs
to show this.
The left-over ActionDisplayt::Head documentation is,
unsurprisingly, wrong. Rack::Head code behaviour is not to change
HEAD into GET it is to close the body of all HEAD requests.
This commit fixes the docs to show this.
As a contributor, changing a single line to test the desired version does not warrant a separate file for each type of report.
The only argument I can see for keeping the gem versions is that users are likely reporting a bug for a specific version of Rails, typically during an upgrade. As few people are probably testing their applications against Rails main branch.
Additionally, having the gem version templates means that we are testing both main and a stable release of Rails in CI, which has some benefit.
By removing the edge version templates, we also lose that coverage in CI, but I think it's something we can fix in buildkite-config to replace the line in those guides before running them later.
IMO, the cost of separate files and the confusion it will create if we want to add more templates outweighs the benefits mentioned here.
My motivation is that I want to add more report templates, like for additional adapters, and this list will grow to be unmanageable if we keep the gem versions.
Add guidance to the Association Basics and `.belongs_to` method
documentation to encourage the renaming of a model's Ruby class to
coincide with updates to the existing data in the database.
Since Action Text and Active Storage rely on polymorphic associations,
add similar warnings to their guides.
Co-authored-by: Petrik de Heus <petrik@deheus.net>
Co-authored-by: Stephen Hanson <s.hanson5@gmail.com>
Co-authored-by: zzak <zzakscott@gmail.com>
Upgrading Rails to "at least 2.1.1" is outdated advice. Applications
should run 7.0.Z or 7.1.Z.
Also, RedCloth version 4 is from 2009, so I don't think it's that "new".
- Explain the purpose of wrap_parameters_by_default and how it replaces
the wrap_parameters initializer.
- Explain why action_mailer.smtp_timeout exists and why its useful
- Add example to action_view.button_to_generates_button_tag
When set, validates that the timestamp prefix for a migration is in the form YYYYMMDDHHMMSS.
This is designed to prevent migration timestamps from being modified by hand.
It is turned off by default.
The new documentation explicitly lists all "autoload paths" for the
reader, and mentions the `add_autoload_paths_to_load_path` config toggle
Co-authored-by: Matt <iMacTia@users.noreply.github.com>
Association callbacks were missing in the callbacks guide.
We can still keep a small section in the associations guide that links
to the callbacks guide.
The ordering can now be configured.
Also update the Configuring guide and API docs. In the Configuring guide
"When true" seems more common than "When false", so that is used
instead.
Co-authored-by: Akhil G Krishnan <akhilgkrishnan4u@gmail.com>
Rename "Dealing With Consistency" heading to "`after_commit` and
`after_rollback`. To be more inline with other headings.
The "Context Matters" heading has been renamed to "Aliases for
`after_commit`", as this section is about aliases and `Context Matters` is
a bit ambiguous.
The warnings for `after_commit` and `after_rollback` better fit with the
section about these callback methods.
Sean Doyle