TL;DR Please mention delivery_job on action_mailer_basics.md with an example of how, and maybe even why you need it (to specify custom job configuration such as to allow using
sidekiq_options retry: false and/or to specify a non-default background worker queue handler and/or queue name.
I’ll start with the domain issue… IMO (after many millions of emails sent via my Rails apps) it is a Very Bad Idea to implement any mailer without explicitly disabling automatic retries… and yet that’s often a default behavior for emailers on a lot of stacks… which explains those times your inbox (like mine) was flooded with a zillion copies of the same email from a company - even Microsoft - because the email DID go out but something downstream (like the “sent acknowledgment handshake”) timed out repeatedly so the job “failed”, so the email was re-sent a few minutes later, until some max-retries was reached.
ActionMailer may, or may not, have retries enabled by default (no mention on the AM docs). I’ll hazard a guess that since ActiveMailer magically uses ActiveJob (with zero docs other than “Action Mailer is nicely integrated with Active Job”), it probably retries emails unless your Sidekiq (for example) config explicitly turns off retries for ALL jobs (probably not what you want).
AFAIK there is literally no way in ActionMailer to directly specify essential mailer settings such as explicitly disabling automatic retries* other than than to create a custom ActiveJob class rather than use the magic (but completely obfuscated) connection between ActionMailer and ActiveJob. (Which makes sense, that is a logical concern of the job not the mailer.)
So documenting a simple example of (and example reasons for) implementing a custom ActiveJob class for ActionMailer seems like a broadly useful addition to action_mailer_basics.md
Just as an aside… even if you know the answer is to “somehow tell ActionMailer” to use a custom job class I challenge anyone to “google” how to do that successfully without already knowing the keyword delivery_job. And even worse, if you do already know that keyword, I find precisely one example on the first 3 pages of google results.
It’s a very well-hidden secret for such an important and couple-years-old addition.
ANCILLARY ISSUE: “why not submit a PR”
Answer: Is there anywhere a step-by-step guide to creating a PR for Rails Guides.
I’m admittedly dumber than the average bear, but it is completely non-obvious to me - someone who has managed to use Rails quite productively for a decade - but who hasn’t needed PRs. It is a fair bit of additional overhead for a simple “I suggest you add this para to to your docs”.
In the absence of any clear step-by-step guide (AFAIK) a PR-newbie has to figure out a few things entirely unrelated to their problem at hand to simply suggest the addition of a useful new para for docs.
If you are opposed to the common (and far easier for users) process of adding “feedback on this page?” button to the guides, the next best thing would be a literal step-by-step for doing a PR to whatever the right place is for doc changes to the Guides.
I fully understand why PRs are better for the core team to manage a zillion external inputs, I’m just saying folks might have used Rails productively for a decade without ever having done a PR, and might even have something useful to contribute - like poorly documented things they found confusing then figured out - if the PR process for your guides is better documented as opposed to being a couple hours of deciphering the PR process first.
You can get ALL the way through About pull requests - GitHub Docs without it being made clear what the prerequisite steps are (which repo, rails or do Guides have their own? download locally? clone locally? or copy to your own github account first THEN download locally? create new branch locally? make changes? THEN get started on the actual PR? What if I use bitbucket not github for all my own repos? create a github account presumably is required?).
None of it is hard (once you know it). But just perhaps not entirely clear to some of the very folks who are likely to be the ones to a) get confused about X, b) figure out X, and c) have some suggestions for docs about X.