Purpose and progress

Several callers can use one PC at the same time: the developer, agents in sandboxes and test scripts. A purpose says what a fleet or machine is being used for. Progress is the caller's own count of how far that work has got. With both, the developer can tell a run that is nearly done from one that has just begun, and a slow run from a stuck one, as long as the caller keeps its count up to date. East India stores both and shows them. It does not run or understand the work, and it never estimates progress: a bar moves only when a caller reports a count.

Recording what a run is for

Give the fleet its purpose when you launch it. The title is one line; the notes are an optional Markdown file, such as what the run covers, whom to ask and what not to touch:

Terminal
endia compose -p "$run" up --wait --purpose "Regression run 412" --purpose-file notes.md

Write the title for the person watching the PC. The desktop app shows it on Home, on one line, beside each running fleet, so say in plain words what the run is doing and why, in about 60 characters or fewer: Checkout smoke tests before the 2.4 release, not smoke-2/test_checkout.py_test_pay_with_card_as_admin. File names, folders, test IDs and timestamps belong in the notes file, where the app shows them in full. A longer title is cut off with an ellipsis.

Change it at any time with endia update, which names a fleet or a machine:

Terminal
endia update "$run" --purpose "Regression run 412, retrying the login tests"
endia update "$run-client-1" --purpose "Debugging the login timeout"
endia update "$run-client-1" --purpose ""

endia purpose show <fleet or machine> prints the purpose in effect, who set it and when, then the notes as plain text. With --history it also lists each change. When a name belongs to both a fleet and a machine, endia update and endia purpose show ask you to choose with --fleet or --machine. endia compose down writes the fleet's history to its operation log before it removes the fleet, so the record outlives the run.

Reporting progress

A caller reports progress as counts of whatever it counts, such as files, tests or images:

Option Set on Meaning
--progress a machine The progress: how much of the work the machine has done, a whole number from 0.
--workload a fleet or a machine The workload: the total amount of work, a whole number from 0.
--stage a fleet The stage: what the work is doing now, in your own words, 1 to 200 characters without a line break.

A fleet's done figure is always the sum of its machines' progress, so a fleet takes no --progress count of its own. East India shows a stage exactly as given and reads nothing from it, so a step number such as Run tests 2/2 is part of the text.

When the machines hold the workloads but a running machine has none, the fleet is open-ended: the bar shows how far the measured work has got, and that more work is still running.

A nightly run

The fleet nightly has three runners and a cache, nightly-shop-1. The first stage counts images on the fleet; the second counts tests on each runner:

Terminal
endia update nightly --purpose "Nightly build and test" --stage "Build images 1/2" --workload 3
endia update nightly-runner-1 --progress 1
endia update nightly --stage "Run tests 2/2"
endia update nightly-runner-1 --progress 30 --workload 120
endia update nightly-runner-2 --progress 20 --workload 80
endia update nightly-runner-3 --progress 10 --workload 100
endia update nightly-shop-1 --progress 0 --workload 0
endia update nightly --progress -1
  1. After the second line, Home shows Build images 1/2 with the bar at 33 per cent, 1 of 3.
  2. The new stage removes the counts and the fleet's workload, and adds Build images 1/2 with 1 of 3 to the history. Home shows Run tests 2/2 with the infinity bar until the runners report.
  3. Once the runners have reported, Home shows 20 per cent, 60 of 300. nightly-shop-1 is left out of the sums.
  4. The last line removes the fleet's progress, and Home shows the infinity bar again while the fleet runs.

endia update prints the name of the fleet or machine it changed. endia purpose show nightly prints Stage: Run tests 2/2 and Progress: 60 of 300 (20%); a support machine shows Progress: 0 of 0 (support). endia ps --format '{{.Progress.Progress}}' prints each machine's count.

Removing a value

As with Docker's docker update --memory-swap -1, -1 removes a number and "" removes text:

Option Sent to Values removed
--progress -1 a machine The machine's progress and its workload.
--workload -1 a machine The machine's workload only.
--workload -1 a fleet The fleet's workload, after which its machines may send their own.
--progress -1 a fleet All the fleet's progress: its stage, its workload and every machine's counts. The stage that ends goes into the history.
--stage "" a fleet The stage, with the counts, as a new stage would.
--purpose "" a fleet or a machine The purpose, and with it the progress of the same fleet or machine.

For example, endia update nightly-runner-2 --workload -1 removes that runner's workload and keeps its progress.

In the desktop app

Home shows each running fleet's bar under its purpose. The fleet's purpose card, the machine's page, and the Progress columns of the fleet list and the machines table show bars too.

The stripes stand still when Windows is set to show fewer animations. A screen reader reads the bar as its figure, such as 20 per cent, 60 of 300, or as Running, no total given. East India's own operations, such as a build, keep their plain progress bar, so the ship always means a caller's count.

Errors

Error When
PROGRESS_CONFLICT A machine sends a workload while its fleet holds one, or a fleet sets a workload while any of its machines holds one. The message says which holds the total: nightly holds the workload; send the machine's progress only, or machines of nightly hold workloads; remove them first.
INVALID_REQUEST A machine sends a workload without its progress, or a machine sends a stage, which belongs to its fleet.
exit 125 endia update without an option, a count that is not a whole number from -1, a title with a line break, notes over 65536 bytes, or --purpose-file without --purpose. Nothing was sent.

None of these changes is an operation: each command answers at once.