| [RF-Docs] [ci-skip] Active Job Basics guide (#57101)
The purpose of this PR is to update the Active Job Basics guide as part of the Rails Foundation documentation project.
Here's a high level of the changes:
- Restructured the entire guide top level sections and subsections so that it's more cohesive. Removed tiny sections that were not adding any value (as noted in the audit)
- Rewrite the big Solid Queue section and restructure it's subsections with the objective of giving the reader a more of a conceptual overview of how Solid Queue is designed, what's unique about it, how it compares to other queuing backends and highlighting it's features and how to use it in practice. I removed the existing content that was mirroring what is already in the Solid Queue README on Github, so we are not duplicating that.
- Addressed all of the comments from the initial audit
- [X] Nitpick: "Create and Enqueue Jobs" should probably be changed to "Creating and Enqueuing Jobs" which is more common in the guides.
- [X] Maybe the bulk enqueuing top section should be inlined under "2.3. Enqueue Jobs in Bulk" instead of linking to it? It's not a big section
Solid Queue
- [X] should “asynchronous in-process queuing system” be renamed to “asynchronous in-process queuing backend”
- [X] The the queue in the database.yml examples for development and production could be made clearer by highlighting the queue lines. -> good call
- [X] The order of the defined queues having precedence over job priority might be made clearer if we show an example of the defined queues (production and background) -> Rewrote this
- [X] ⚠️ is used for warning. A WARNING block should probably be used instead. Although this would require some rewriting as we probably don’t want to wrap the whole section in a WARNING block.
Queues
- [X] Maybe this section should be renamed to something like "Enqueuing Jobs" to better describe what it is about? It's not really about the queues itself. -> Restructured the sections
- [X] Maybe add titles to split this up in sections: "Naming Queues" and "Dynamic Enqueuing"? -> Restructured
- [X] Maybe we should recommend a naming scheme for queues? [Latency based naming](https://engineering.gusto.com/scaling-sidekiq-at-gusto-3f9e3279e63) is a popular option. Jean Boussier: "You can mention it as a popular option without making it a recommendation." -> good one, added the recommendation.
Priority
- [X] I think this section can be a sub section of the "Queues/Enqueuing Job" section.
Callbacks
- [X] The callbacks examples could be made clearer by using line highlighting for just the callback code.
- [X] None of the callbacks are described unlike other guides where we describe the callbacks. -> added code snippets for all
- [X] There is an open PR to add a section about halting callbacks, which makes sense to mention: https://github.com/rails/rails/pull/53541 -> thanks for the heads up, added the halting section!
Bulk Enqueuing
- [X] "perform_all_later is a top-level API on Active Job." doesn't seem to add anything and could be removed?
- [X] If we have a "Enqueuing Jobs" section this could be a sub section.
ActionMailer
- [X] This section can probably be removed as this is already described in the ActionMailer guide. Other frameworks also use ActiveJob but aren't mentioned, for example ActionMailbox `incinerate_later` and ActiveStorage `purge_later`. -> +1 removed!
Internationalization
- [X] This section also doesn't add much and seems more related to ActionMailer.
Supported Types for Arguments
- [X] This section seems relevant to the "Enqueuing Jobs" jobs section and should probably be a sub section of that? -> moved to a new section about defining a job
Exceptions
- [X] I think renaming this title to something like "Handling Failed Jobs" better describes what this section is about.
Job Testing
- [X] Could probably be removed? Do we have sections like this for other frameworks? -> removed, doesn't add value agree.
Debugging
- [X] Maybe this should be a part of the "Exceptions" top section?
- [X] Verbose enqueuning logging is enabled by default in development so I don't think it deserves it's own section.
Alternate Queuing Backends
- [X] Maybe it makes sense to move this section after the Solid Queue section? Or we can keep it at the end if we really want to de-emphasize alternative backends. -> restructured such that those sections are next to each other.
Co-authored-by: Ayush Newatia
Co-authored-by: Petrik de Heus
Co-authored-by: Abdelkader Boudih
Co-authored-by: Tim Tilberg
Co-authored-by: Ahmad hamza |