saltstack / saltstack/salt

[DOCS] Improving returner docs

Open
#63,367 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

doc-rework documentation module doc standards severity-medium time-estimate-sprint
Dominant language
Python
Stars
15.7k
Forks
5.6k
Avg merge
2d 44m
Merged PRs (30d)
80

Description

Description
The docs do a very bad job at explaining the difference between ext_job_cache, event_return, master_job_cache, --return and which returner modules support which contexts.

Suggested Fix
Clarify the following:

  • The difference between the master options (I don't currently understand this)
  • How --return works (does it ask the minion to send the data, and does this relate to the master options? which master option sets the argument's default value?)
  • How to tell if a module can be used in a given master option (it is unclear to me which exact functions this depends on)
  • Which options should be on the masters and which should be on the minions

Location or format of documentation
https://docs.saltproject.io/en/latest/ref/returners/index.html
https://docs.saltproject.io/en/latest/topics/jobs/external_cache.html
https://docs.saltproject.io/en/latest/ref/configuration/master.html

Additional context
I am more than happy to write the documentation, but I need to know how the returner system works before that and if the links above are the correct place to add documentation to.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the returners index, external cache documentation, and master configuration documentation linked in the issue. Trace how ext_job_cache, event_return, master_job_cache, and --return relate before updating the relevant documentation. Done means the master and minion options, supported contexts, module requirements, and --return behavior are clearly explained.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.