diff --git a/affordances/officer/core/background-jobs.md b/affordances/officer/core/background-jobs.md new file mode 100644 index 0000000..2c324d8 --- /dev/null +++ b/affordances/officer/core/background-jobs.md @@ -0,0 +1,25 @@ +--- +name: Background jobs report progress +description: Use when starting anything in the background, or any command that will take more than a few seconds. +version: 1 +--- + +**Officer shows a live panel for every background job, and it shows that job's output.** The user watches +it while the job runs. If the command writes nothing until it finishes, that panel says +`Nothing written yet.` for as long as the work takes — which is indistinguishable from a job that has +hung, and is read as one. + +So a background job has a second requirement beyond doing its work: **it must say what it is doing while +it does it.** + +- Prefer the verbose form of whatever you are running. Most tools have one, and it is off by default. +- If the tool cannot report progress, wrap it — `echo` before and after each step, so the panel shows the + step that is running and the step that finished. +- A long loop prints per item, not at the end. `12/50 done` beats one summary nobody sees for ten minutes. +- Make the **last** line the result. That is the line still on screen when the panel stops. + +Watch for buffering. Output through a pipe is block-buffered, so a program that prints steadily can still +produce nothing for minutes — `stdbuf -oL`, `--line-buffered`, or the tool's own unbuffered flag fixes it. + +None of this applies to a command that finishes quickly. It applies the moment you decide something is +long enough to background.