The web interface
workflow --web serves the same loop in a browser: the same issues, branch,
pull request and announcement the terminal interface shows, read from the same
repository and services through the same code. It is another way in, not a
second implementation, and the terminal stays the fuller of the two.
Start it
workflow --web # serve http://127.0.0.1:13579
workflow --web --dry-run # the same, read-only
workflow --web --port 7001 # serve http://127.0.0.1:7001Run it inside a repository, then open the address it prints on stderr,
which looks like http://127.0.0.1:13579/#session=…. It listens on the
loopback interface alone, on port 13579 unless --port names another (1 to
65535; --port goes only with --web), and refuses a write from a page
served anywhere else, so a site open in another tab cannot drive it; nor can
a site show the page inside one of its own. ctrl+c in the terminal stops
it. Closing or reloading a page stops what the server was still reading for
that page alone; a change the page asked for goes on to its end, unless
ctrl+c stops the server first.
The session. Each run makes a session as it starts, and only a request
that presents it is answered, so another program or another account on the
machine cannot drive the server just by reaching the loopback address. The
address it prints carries the session after #session=, in the part a
browser never sends to a server: the page keeps it in this browser for that
address, takes it out of the address bar, and presents it on every request.
A tab opened later at the same address uses the one kept. A page opened
without it, or after the server was started again, says to open the address
the running server printed. Treat that address as you would a password while
the server runs; it is no use once the run ends. With no .workflow.json to read, it
says so on stderr and serves anyway: Settings sets a first one up (see
Setting up), as workflow config init does at a prompt.
Every build carries the web app inside it: the release binaries, task build
and go install alike.
Read-only with --dry-run. A banner under the header says so, and every
write is held back in the browser before it is sent, saying Held back by
–dry-run: nothing was sent. The server refuses every write as well, so
nothing changes even if a request gets past the page. Unlike the terminal, the
web does not narrate what a held-back write would have done.
The page
The header holds the version, where the server works, the theme and the stream’s state. Under it runs the loop: the checked-out branch’s five stages — Issue, Branch, Commits, Review and your messaging service — each with its state’s mark and a rule that fills in its system’s color as the stage gets done; the Review rule fills as CI’s checks finish. A stage not yet begun is faint, and a failed one red. The Taskwarrior task you have started, when there is one, ends the loop’s row, or takes a row of its own on a narrow window. The rail down the left holds the nine sections; the one you are in, and its heading, take the hue of the system it belongs to. Below a medium width the rail keeps its icons alone; each still has its name, shown on hover and read by a screen reader.
The theme button cycles System, Light and Dark. System follows your operating system; the choice is remembered in this browser.
The type is Recursive, one variable face the binary carries and serves
itself, so the page fetches nothing from elsewhere: proportional for what you
read, and at its monospaced setting for what you would type into a terminal —
a branch, a commit, a path. It covers the Latin alphabets; text in another
script draws in your system’s own face beside it. Its SIL Open Font License is
served beside it, at /fonts/Recursive-OFL.txt.
The stream keeps the page current. Every five seconds, and at once after
anything you do here, the server pushes each open tab what it finds, so
nothing on the page needs refreshing by hand. What you do says it is done only
once a push read after it is on the page, so its word comes with a page that
shows it done: the server numbers what you do, and each push counts what it
was read after, so a push already going out at that instant, or one that
arrived first, is told apart from the one that shows it. Each push reads the
repository afresh — the branch, the working tree, the branches and worktrees,
the commit scope — and Taskwarrior, all on this machine. What it asks over
the network is shared by every tab: the issue search is made at most once
every timing.ci_interval (twenty seconds unless set) for each view, and
again on the next push after a status change or an assignment made here,
and each search’s first page is kept in the store for the next session, as
the terminal keeps it (never under --dry-run); which of the branches'
issues are yours, once a minute, and again after an assignment made here;
the forge — the pull request, its reviews and its CI — at most once every
timing.ci_interval, and at once when another branch is checked out or
its head commit moves, while a pull request the page opens shows from the
open on, without asking the forge, and until the forge’s list of the
branch’s pull requests includes it, each read asks for it by its number; and
who the forge says you are, until it answers, at most once every
timing.ci_interval. A tab that has an answer to show is not held up by
another tab’s read of the forge or the tracker, except after an edit, a merge,
a finish or a re-run of the pull request, a status change (a move to review
among them), or an assignment, made here: the next push waits for the read
that follows it, so it shows what changed. A forge read that fails keeps the
last answer for the same branch and head commit, and says why beside it. A
read that fails shows as a failure in its section, with the reason, rather
than as an empty one: the Issues list does not say no issue matches, the
Branch section does not say the directory is no repository, and the Review
section does not offer to open a pull request, while Jira, git or the forge
cannot be read. A service that is not set up — no Jira or forge token, a base
remote that names no forge — is no failure: the section says, in the muted
color beside the not-started mark, that it is not set up and how to set it up,
in place of what it would have shown. When the store holds the view’s issues
from an earlier read — the terminal’s or this page’s — the server sends them
first, read from disk before anything is asked of the network, so Issues lists
them at once while every other section waits for the first update; --dry-run
neither reads nor keeps them. The stream’s state is beside the theme, and a
section waiting on its first update says the same word:
- Connecting — the page has not had its first update yet.
- Live — updates are arriving.
- Reconnecting — the connection dropped; the browser is finding its way back, and the page shows the last update until it does.
- Out of date — updates arrive but this page cannot read them, which happens when the server is a newer or older build than the page. Reload the page. Why is shown on hover and read by a screen reader.
- Disconnected — what answered at the page’s address was not workflow’s stream, so the browser gave it up: another program on the port, or a server that failed before it could answer. Reload the page once workflow is running there.
The forge’s own words. On GitLab the page says merge request and numbers
one !12; on GitHub, pull request and #12 — as the terminal does.
The keyboard. Beyond Tab, the page answers the terminal’s own keys, read
from its bindings with ui.keys applied, so a key you moved in the file moves
here too. ? opens a sheet of the actions the page has a control for, under
the terminal’s groups, one for each of its panes (its Commits pane’s keys,
which work on Branch here, keep a heading of their own), and in its words,
with the key for each; Escape closes it. Ctrl+K, or ⌘K on a Mac, opens a palette of what the section
you are in can do (in a Mac’s text field Ctrl+K stays the field’s own key), and of the other sections: type part of an action’s
name, choose with the arrow keys, and Enter runs it through its own
button, so a push or a merge still asks first. Single keys — c comments,
a stages everything on Branch, 2 opens Branch — are off until you turn
on Single-key shortcuts in Settings (ui.web_shortcuts), since a key
that acts on its own surprises a screen reader or speech user; ? and the
palette work either way. Even with them on, a key types into the field that
has the focus, a search box or the comment box among them, and acts only
outside one; and while a dialog is open — the sheet, the palette, the
directory dialog — no key reaches the page behind it. Nor does any key, ?
and the palette included, while a confirm, a preview or a form that writes
in place — an assignment, a status change, logged work, an amend, a merge —
waits on your answer; Settings’ own form holds none. The navigation stays a
click away for a deliberate leave. Each control a key reaches says so to
assistive technology (aria-keyshortcuts). See
Keys on the web.
The sections
Issues
Here the detail is scrolled past PROJ-412’s key, status, title, type, priority, reporter and assignee to its actions and its whole work story; the selected row beside it shows its key, status and title.
The issues in a view — the default is those assigned to you and not done —
with a View select for the views your configuration defines, each scoped
to your issues unless its query names the assignee, a Search over the
issues loaded so far, by key or summary, Filter buttons that narrow them
to places, and Load more while the view holds more, which reads on from
the last issue loaded, wherever the view has moved it, so an issue joining or
leaving the view above it neither skips nor repeats a row. Filter offers the
statuses the loaded issues are in, in the workflow’s order as the terminal
lists them, and the marks in flight, task active, tracked, task done
and forge issue, each with how many issues it holds; pressing one narrows
the list, and pressing it again undoes that. Statuses widen each other, as
marks do, and the two narrow together, as the terminal’s f does. A
repository that lists its forge’s issues beside Jira’s (issues.forge)
numbers them as the forge does, #57, links each to its page with Open in
GitHub or Open in GitLab, and says so above the list, among its
controls, when the forge’s issues could not be read. An issue with a branch is
marked in flight, with Switch branch beside it when that branch is not
the one checked out — a local branch, or one only the remote has, which
checking out creates here. The branches counted are those naming an issue
assigned to you and not done, so a branch whose issue was finished or
reassigned no longer marks it; while the tracker cannot be asked, its last
answer stands, and a branch it has not answered for yet counts until it does.
Once Taskwarrior has answered, a row also marks how its issue’s tasks stand:
tracked, task active or task done. Until the first update, the list is
the one last kept for the view, saying Reading Jira… these are the issues it
listed last time., with no row marks and no Load more until Jira answers;
a switch of view does the same for the view switched to, its rows marked from
the last update.
The selected issue’s detail shows its type, priority, reporter and assignee, a
link to open it in Jira, its description and its comments, and its work
story: the loop’s stages, titled as the terminal’s top row and workflow status name them — Issue, Branch, Commits, Review, and the messaging service
the work is announced on, such as Slack — each opening the section it belongs
to. Each step reads done, in flight, not started or failed as the server works
it out, by the rules of the terminal’s top row and workflow status. For the
issue whose branch is checked out, the issue is done once the branch names it,
the commits once there is one, and the review once the pull request’s CI
passes or it merges, failed on a CI failure or changes asked for. The
announcement is done once the pull request was announced at the moment it is
at now — from the browser, the terminal or workflow announce, as the store
remembers — but not for one closed without merging, which the loop no longer
follows. The server reads the working tree and the forge for the
checked-out branch alone, so for an issue on another branch only the issue
and the branch read done, and for an issue with no branch yet the issue reads
in flight, picked as the terminal’s top row reads an issue selected, and
nothing after it begun. From the
story, Start work fetches the base remote — upstream in a fork’s clone, else
origin — so the branch starts from what it holds now, then creates and checks out a branch named for the issue, and
Switch branch switches to one it already has. Start work in a new
worktree creates the branch in a new git worktree beside the repository
instead, leaving the checkout here as it is, then says where and offers
Switch to it. A branch another worktree has checked out, which git will not
check out twice, offers Switch to its worktree in place of the checkout.
Either asks “Switch to DIR?” first, as every switch in Repositories does, and
switches only on Switch there; one held by a worktree whose directory is gone says that git worktree prune
frees it. When the fetch fails — the network, the remote’s address, your
credential — nothing is made, the reason is said, and Branch from what you
have starts the branch from the base as it was last fetched, as the
terminal’s branch creator offers. Once Taskwarrior has
answered, a Tasks card sits between the story and the description;
Tasks says what it holds. Below a large width the list sits over the
detail rather than beside it.
Under the people, three buttons change the issue, as the terminal’s t, a
and w do. Change status lists every status change the tracker offers
from where the issue stands, each by where it leads, named when the change
has a name of its own, and saying which fields it needs. Choosing one shows
its form: a choice of one value, a box per value for a list such as fix
versions, a date, or text or a username. Change to the status sends the
change with what was filled, and nothing is sent before that press; a field
left empty or given something it does not take is named beside the form, and
nothing changes. A change that needs a field only Jira’s own screen can fill,
such as a cascading select, says so and cannot be sent from here. A forge
issue offers one change, Close. Assign sets the assignee to the username
typed, as the issue’s tracker knows it. Log work, on a Jira issue alone,
logs a duration in Jira’s words — 2h, 30m, 1d 4h — with an optional
note. Each form says what it did once the tracker has it — Changed PROJ-1 to
Resolved., Assigned PROJ-1 to ana., Logged 2h on PROJ-1. — and reads the
issue again; a refusal stays beside the form, which keeps what was entered.
Cancel sends nothing.
The comments are drawn from Jira’s wiki markup: bold, italic, struck and code
text, links, headings, quotes, lists and code blocks. Anything else, such as a
table, a panel or a color, shows as the text it is, and an image is offered as
a link rather than loaded. A link opens in a new tab, and only to an http or
https address; one to anywhere else, an email address among them, shows as
the text it is. Under the thread, a box takes a comment; on a Jira
issue it says it is reading how comments are written until the configuration
answers, then draws in that shape. On a Jira
issue the comment is Markdown, as jira.markdown_comments is on by default:
Write and Preview are tabs, Preview shows it as Jira will, and the
buttons beside them write bold, italic, code, a link or a list around what is
selected. With it off, the comment is posted as typed, and Jira reads it as
wiki markup. Turning it on or off in Settings applies to the next comment,
with no restart. Comment posts it and reads the issue again, so the thread
shows it as Jira keeps it.
A forge issue, numbered such as #57, takes a comment too. Its thread and its
comment are always Markdown, which the forge renders itself, so the box always
has Write and Preview, and the comment is posted as written. On GitLab the box
also says that a line starting with /, such as /close, runs as a quick
action rather than being posted. A comment over 65,536 characters, or with a
line over 1,000, is shown as plain text in the thread and in Preview, and so
are a thread’s older comments once the newer ones add up to that many.
Branch
The checked-out branch, its base, its upstream and how far it is ahead or
behind, and the commits on it; Push to names the remote a push goes to when
that is not the base remote, as in a fork’s clone. Push branch publishes it, after a
confirmation naming the branch and the remote it goes to; it is not offered
on the base branch itself. A branch git could not count against its upstream
says it is not counted against it, and is offered the push, since that
upstream is not known to hold its commits. Link an issue ties a branch begun outside workflow, whose
name names no issue, to one: a Jira key or a forge number such as #42. When
its pull request’s description does not name the issue yet, it is shown with
the issue’s line added first, with Link and update or Link only. A
linked branch says so, with Unlink; the link is kept in the repository’s
git configuration, as the terminal’s i keeps it. Rebase onto the base
replays the branch onto it, as the terminal’s u does, after a last look
that says its commits are rewritten.
Under Working tree, each changed file has its own Stage or
Unstage, and Stage all stages the rest; Unstage all beside it
takes everything out of the index at once, as the terminal’s U does,
leaving the work tree as it is. Discard… on a file asks first, as the
terminal’s x does, since it cannot be undone: Discard puts the file
back as the last commit has it, staged and unstaged changes alike, and
deletes a file the last commit does not have. The commit form builds a
Conventional Commit from its type, scope, subject, body and a breaking-change
box, with the scope the terminal would suggest already filled in; Commit
staged changes commits, adds the trailer naming the branch’s issue (Refs:
unless commit.refs_trailer relabels it), and runs the repository’s own
hooks. A hook that refuses the commit says why. Show diff under a changed
file reads its diff against HEAD, staged and unstaged together, and reads it
again when a commit moves HEAD or the file is staged, unstaged or renamed,
showing the old diff until the new one comes. An edit to the file’s contents
alone does not read it again: Hide diff puts it away, and Show diff
reads it afresh.
Under the commits, Run a hook reads the hooks lefthook configures and
offers the ones a run by hand can stand in for, as the terminal’s h does,
with pre-commit chosen first; it lists the rest, the hooks only git runs,
with what git hands each. Run runs the one chosen at once, as git would,
without committing or pushing: it changes nothing that leaves the machine.
While something is staged and a commit is not yet pushed, Amend last
commit folds the staged changes into the last one, keeping its message, and
Fix up a commit records a fixup! of the one chosen among those not yet
pushed — the terminal’s A and f — each after a last look at the commit it
rewrites. A rebase, a hook, an amend and a fixup each show their output as it
is written, with Stop, which stops the program and all it started, then
how it ended, with Close. One goes at a time, and it holds the index, so a
stage, a commit, a checkout or a setup of lefthook’s hooks asked for meanwhile
waits for it. It goes on to its end if
the page is closed, and a page opened meanwhile shows it running with its last
lines. A conflict stops a rebase midway, for a terminal to finish.
When the repository’s .git/hooks holds hooks lefthook does not manage, and
it configures no lefthook, Set up lefthook shows the hooks and the
lefthook.yml that runs them, as the terminal’s g offers it; Write
lefthook.yml writes it and installs lefthook, and Write every hook as a
script keeps each hook whole under .lefthook instead. lefthook keeps the
old hooks as .git/hooks/*.old.
Review
The branch’s pull request — its number, title and state: Draft or Ready for review while it is open, Merging while GitLab merges it, when nothing is offered on it, Merged or Closed once it is done — and the issue it is for, linked to its page. While it is open, the section also shows its mergeability, approvals and requested changes, and its CI checks, headed by how many are done when the forge counts them and by how CI stands when it does not, as for a GitLab pipeline, or “No checks reported.” when there are none — “No checks reported yet.” until the head has reported none through ten minutes of the server’s reads: a failed one names the stage it ran in and why it failed, and Show log reads the end of any check’s log the forge keeps one for, passed or failed.
Under the state, the terminal’s Review pane’s writes, each offered only when it
can go and each sent from a form that is its last look: Edit pull request
reads its title and description afresh and Saves them, as e does;
Merge, once it is ready for review, free of conflicts, approved with no
changes asked for, and green or with no check reported on its head through ten
minutes of the server’s reads, from its start and from each new head — until
then its CI checks say none are reported yet, and the form then says no CI was
reported in those ten minutes, and a forge that requires checks refuses it —
reads the methods the repository permits and merges by the one chosen, as M
does; Re-run failed checks, while its CI has failed, restarts the failed
jobs, as R does, says when a failure had no job to restart, and restarts none
on a GitHub commit with more workflow runs than it reads, saying to re-run them
on the forge; and once it has merged, Finish the branch shows the three git
commands it runs — switch to the base, pull it from the base remote, delete the
branch — as F does, when deleting the branch loses nothing: it is at the
commit that merged, or its upstream holds every commit on it, and it has no
commit made after the one that merged, which the server fetches first when this
clone lacks it; a fetch that fails is in the way too. When something is in the
way, the section says what in its place, as the terminal does. The server reads
the pull request and its CI again before each, so nothing goes on what the page
showed a moment ago. A token without the scope a write needs is told in the
forge’s own words, naming the scope.
With no pull request for the branch, Open a pull request
composes one as workflow pr would and shows it as a form: the title, the
base, the reviewers, assignees and labels, the description, and whether it is
a draft. When the repository has several pull request templates, Template
chooses the one the description starts from, as the terminal’s ctrl+t
does, until the description is edited. The reviewers start as the code owners of the paths the branch
changes, as the base’s CODEOWNERS names them, leaving you out; a team is
written org/team and is requested as a team. Name another Base branch
and leave the field, and the branch is read again past it: the title, the
description and the reviewers you have not changed are proposed again from the
commits that pull request would merge, and a base no branch answers to keeps the
draft and says so. Open pull request pushes the branch first when it is not
published, then opens it. If the forge would not add every reviewer, assignee
or label, a warning says so.
Right after the page opens one, the section offers what the terminal and
workflow pr offer next: Link it on the branch’s issue, and Move the
issue to the review status your configuration names, when that move needs no
fields filled in. A pull request opened in the terminal or with workflow pr
gets neither offer here.
With messaging set up, the page also arms the pull request’s announcement as
it opens: a line says Announces to #dev once CI passes. To drop it, press
Stop waiting in the Slack section., and the messaging section shows it
waiting, as one held with Announce when CI passes does — for the forge to
list the pull request just opened, through a failed run, and up to ten
minutes with no check reported. One armed as it opens never replaces another
pull request’s announcement that waits or is being posted: none is armed, and
the line says which one still waits. It tags those
workflow announce --yes would propose, the linked code owners of its changes
against the base it opens into and the groups that start checked, and, as a post
from the preview does, whom it can when the Slack token lacks a scope. A draft
is never armed, and the line says to announce it once it is ready;
messaging.auto_announce: false arms nothing. The open’s answer carries the
armed announcement as announcement (its automatic set), or why none was as
not_armed.
The messaging service
The preview shows the announcement as it will be sent, in the service’s own
markup: with Slack, a link reads <url|text> there, and Slack shows it as
just the text
(link markup).
Named for the service your configuration uses — Slack, Teams, Discord or
Webhook. It shows where announcements go and who they are from. Announce to
the service composes the announcement of the branch’s pull request and shows
it, with the channel to send it to where there is a choice; Announce now
sends it. Nothing is sent before that second press, and what is sent is the
text shown: when the announcement changed in between — the pull request
merged, say — nothing is sent, the page says so, and Announce to shows
the new one. Once a pull request was announced at the moment it is at now —
ready for review, or merged — from here, the terminal or workflow announce, the section says so in place of the offer, as the terminal offers
no announcement it has made; each announcement made here is claimed in the
store for the terminal and workflow announce too. One whose post began and
was never confirmed — a session that stopped mid-post, or a service that never
said whether it took the post or failed while taking it — may have gone out, so it is not offered again
either: posting it again here is refused with announced_unconfirmed, saying
when the post began, and workflow announce asks before posting it again. A
store that cannot take the claim posts nothing (not_claimed), and a post the
service did not say it took keeps its claim, saying so. With store.disabled
nothing is claimed or kept, so once posted the section offers the
announcement again and posts it again if asked. A pull request closed
without merging is none to announce: the section asks for one to be opened, as
it does with none at all. One GitLab is merging is at no moment to announce:
the section says to announce it once it has merged, and offers nothing until
then. Each announcement is claimed in the store before it is
posted, so two pages, a page and a terminal, or two servers asking at once
post it once, and the second is answered 409. One posted whose claim the store
then cannot confirm — a full disk, say — went out all the same, and the line
saying where it went adds The store did not confirm it; it is not offered
again., as a held one does once it goes, and as the terminal and workflow announce say it; the server’s log says why, which those two print after the
sentence.
Nothing is announced while a check has failed on the pull request. The server
reads its CI again as it posts, whatever the preview showed, and a failed
check keeps it from going, ready or merged alike, with a ci_failed problem
the section shows; a CI the server cannot read keeps it from going too. A
ready-for-review preview whose CI has a failed check offers only Announce
when CI passes, and says why; a post refused for a check that failed after
the preview opened previews it again, offering the wait. A merge has no CI to
wait for, so its preview offers neither, saying to re-run the failed checks on
the forge and announce it once they pass.
Edit, in the preview, turns the message into a box to change it in, as
the terminal’s e opens it in your editor; Announce now then sends the
text as edited. An edit still goes only while the announcement it began from
is the one composed now: when the pull request merged since,
nothing is sent, as for an unedited one. An edit emptied of text is refused.
Until the pull request’s CI passes, a ready-for-review announcement’s preview
also offers Announce when CI passes, the terminal’s w: the server holds
the announcement — edited or not, with its tags — and the section says Waiting
for CI on #42 to pass, then announcing to #dev., with Stop waiting to stop
it unposted, after which the section offers to announce it again. Below them,
while a frame shows it waiting — whichever page held it — the
announce button reads Announce now instead, drawn as a secondary control:
it opens the same preview, and an announcement sent from it settles the held
one as announced once it goes. A pull request just opened waits first for the
forge to list it, and the section says so. The held one is posted
once the forge reports the CI passed, and the section then says it was
announced. A failed run does not drop it: the section says a check failed and it
waits on a fix, and it goes once a later run passes; nor does a read of the
forge, or a post, that failed — the section says what failed and that it tries
again — until the reads, or the post, have failed for ten minutes, when it
is dropped saying which, and how it failed last. A post the service refused
drops it with the
service’s reason; one it did not say it took drops it too, since it may have
gone out, and only workflow announce posts that one again, after asking. While no check is reported
the section says it waits for checks; after ten minutes of reads that heard
none, counted from the last read that saw one, a read that failed not counting,
it is dropped, saying to announce it by hand — a
repository with no CI is announced by hand. CI that runs and reads the same —
no check finished, failed or started — for two hours drops it too, saying CI
on #42 has been running for 2h. When, before its CI passes, the branch’s pull
request is another one, closed, merged, or one GitLab began merging, it is
dropped and the section says why in red. It is bound to the branch it was
asked for on: checking out another branch meanwhile neither posts it nor drops
it, and Stop waiting is the way to stop it. Announce when CI passes
over another pull request’s waiting announcement replaces it, and the section
says so. An announcement
sent now leaves the held one waiting until the post has gone, then reads it as
announced, so the channel never reads it twice; one that fails leaves it
waiting. The server, not the page, holds it: it reads the branch’s pull
request and its CI for it every timing.ci_interval (twenty seconds unless
set), straight from the forge, whether a page is open or not, and a frame only
shows how it stands. It is kept in memory alone, so it is lost, unposted, if
workflow --web stops or switches directory before the CI passes — as one
held in the terminal is lost when the terminal closes — and a post under way
then finishes, its claim keeping it from going twice.
With a Slack user token, a ready-for-review announcement’s preview also says
whom it tags. Tag code owners lists the code owners of the branch’s
changes: one linked to Slack shows their Slack name, one decided not on Slack
says so, and one not asked yet has a field to choose a member of the channel
the preview posts to, narrowed to the names holding what you type and
following the channel as you change it (a team’s, of the workspace’s user
groups), and a Not on Slack button.
The choice is saved as you make it, for this and every later announcement on
the same forge host, and the page says it was saved for next time;
Announce now waits while a link is being saved, and a group checked
meanwhile stays checked. Tag groups
checks the user groups the repository offers; a group a team owning the
changed paths is linked to starts checked and says it “owns changed paths”,
and the rest start as you left them last time. Tags: above Announce
now names everyone the post will tag; the tags go on a line after the
text. The post tags only the people the preview showed: when a link changed
in Settings or a terminal since, nothing is posted and the page asks you to
preview again. A Slack token without a scope linking needs (users:read,
channels:read, groups:read or usergroups:read) for the channel picked
is named in a note, and the announcement still posts, tagging whom it can.
Links are kept per Slack workspace: when Slack will not say which workspace
the token is for, a note says so, nobody is offered, and the announcement
posts untagged; Settings’ people and groups say the same. Under --dry-run
no owner is offered to link. Teams, Discord and a webhook
tag no one, and so does a Slack webhook saved in Settings while the server
runs: tagging follows the configuration in effect.
Reviews
The pull requests on your forge that wait on your review, the longest-waiting
first: where each is, who asks, how long it has waited, whether it is a draft,
and how its CI stands, in the words the filter offers them by — CI none
where nothing reports CI, it could not be read, or on GitHub the request is
past the hundred waiting longest, whose CI alone is read — each with a link to open
it and Copy URL. Where the forge holds more than it lists — GitHub’s
search serves its first thousand, and a GitLab listing is read two thousand
deep — a line says these are only the first. Sort
lists them Oldest first, Newest first or By repository, which heads
each repository’s requests with its name, the longest-waiting first within it —
the orders the terminal’s O cycles through. Filter narrows them, as the
terminal’s f does: a button for each repository, CI state, draft or ready, and
author the queue holds, each with how many requests hold it. Values in one of
those widen the list, and the four narrow it together. A value picked stays
on offer, at zero, once no request holds it, so it can be unpicked; a
repository or author the queue no longer holds comes last. The order and the
filter chosen stay while you visit other sections. The section asks the
forge when you open it, unless it asked within the last 30 seconds, and
Refresh asks again.
Tasks
Your pending Taskwarrior tasks, most urgent first unless you sort them — what
the terminal’s Tasks pane lists, in Taskwarrior’s violet: those for an issue
the Issues list holds first, then the rest, under For my issues and
Other tasks when there are both. A waiting task is counted below rather
than listed, and an active context says it narrows the list. Each row marks
whether the task is started, then its id, what it is, and quietly its issue,
when it is due and its urgency. Sort orders each group by urgency, state,
ID, tag, issue or priority, as the terminal’s O does, and sorted by tag or
priority each row shows its tags or priority, as the filter names them: no
tag or no priority for a task with none. Search keeps the tasks whose
description, project, +tag, issue key or #id holds what you type, and the
Filter chips narrow the list by state, priority, project, tag and whether
a task has an issue, each with its count; pressing waiting lists the
waiting tasks. A started task whose wait is still ahead is waiting there, and
marked not started, while Taskwarrior still counts it started: its detail
offers Stop, and it is not the started task the track shows. A value picked
stays on offer, at zero, once no task holds it, so it can be unpicked, and a
named project or tag, or a named priority other than H, M and L, that no task
holds any longer comes last; a waiting task counts toward its state alone. The
order and the chips stay while you visit other sections. The section reads
Taskwarrior when you open it, when
Refresh asks, and again once the earliest wait still ahead has passed,
since that changes where a task stands with nothing written, rather than from
the stream. It needs Taskwarrior 3.5.0 or newer, found as
Configuration describes;
without one it says why — and, where the task on PATH is another program,
go-task most likely, that taskwarrior.program in the configuration file can
name Taskwarrior’s, which applies once workflow restarts or switches directory.
Settings shows the program but does not change it.
The line at the top adds a task from what you would type after task add, in
Taskwarrior’s own grammar — project:web, due:friday or +review among the
words — and says which task it added. The line is not read as a shell reads
it: each space-separated word goes to Taskwarrior as an argument of its own,
and quotes are passed on as typed, as
Using workflow
explains. The selected task shows its state, project, priority, tags, due
date, urgency, id and issue, a link to the issue’s page and, when the Issues
list holds the issue, Open in Issues. For a task that names an issue the
page is the tracker’s, as the terminal’s o opens it; with the forge’s
issues as the tracker, or for a task that names none, it is the task’s
jiraurl, and only an http or https address.
Then come Start or Stop,
Mark done…, its annotations, and a line each to Annotate it and Modify
it in the same grammar. Undo… reverts Taskwarrior’s last change, whatever
made it, and Sync…, shown when the taskrc names a sync backend, syncs.
Those three ask first and send nothing until confirmed — marking done runs the
task’s hooks, Taskwarrior has no redo, and a sync sends your tasks off the
machine — while Start and Stop act at once. Each write says what it did, and the list redraws from Taskwarrior’s answer at
once; a write that was made when the list after it could not be read still
says what it did, and the section reads the list again, so a write that
landed is never reported failed and made twice by a retry. A task marked
done while the list could not be read again stays in the list as last read,
offering neither Start nor Mark done…, until the list is next
answered, by that read or by another write, whatever the stream says of the
task meanwhile; the section says it leaves the list once workflow next reads
it. A write Taskwarrior refuses says why below its button, in Taskwarrior’s
own words, with your home and data directories put in fixed words and any
line naming a server left out; a failed sync answers in fixed words only, and
task sync in a terminal shows why. A write that changed nothing — Start
on a task already started, say, or Undo with nothing to undo — shows the
sentence its 409 carries.
Once Taskwarrior has answered, the rest of the page shows your tasks too: the
loop under the header ends with the task you have started and how long it has run, and opens
this section; each Issues row marks how its issue’s tasks stand; and an
issue’s detail has a Tasks card listing each of its tasks, with Start
or Stop and Mark done… on each still to do. A task marked done there
shows done at once; when the task could not be read again after the done,
it stands as last read, with neither button, and the card says it shows
done once workflow next reads it. While none is still to do, the card offers
Track in Taskwarrior, which adds the task the terminal’s T would,
annotated with the issue’s page, and says which task now tracks it. Until
Taskwarrior has answered, and where it could not, none of them is drawn,
rather than a claim that no task tracks the issue.
Summary
What you did, read back each time from where the work left a trace: the
commits you wrote in the repository the server runs in and in every favorite
that is one — each named, acme/web@abc1234, when there is more than one —
the Taskwarrior tasks
you added, annotated and completed and the ones you started that are still
going, what you did to Jira issues, and
the pull or merge requests you opened, had merged and reviewed on the forge,
in any repository. It opens on the previous working day — yesterday, or on a
Monday, Friday and the weekend after it — in the time zone the server runs in.
The day reads as a timeline: each hour down the left, and what was done in it
beside it, the verb in the hue of the system it was done in — git’s, Taskwarrior’s,
Jira’s or the forge’s — then what it was done to, linked where it has a page,
and its title. A period of several days or months is headed by month and by
day. A source that could not be read says why above it — naming the
repository, when one of several could not be read — in words that never
name a host, and one that had more than it gave says so. A source that is
not set up — no token, no forge the base remote names, no Taskwarrior installed,
no git user.email — is left out, and says so as guidance with how to set
it up rather than as a failure. Copy as Markdown
puts the summary on the clipboard. Post…, beside it once messaging is set
up, opens a preview of the same Markdown and where it goes, as the Messaging
section previews an announcement: Edit changes the text, the channel is
chosen when Slack offers more than one — a webhook posts to the channel it is
bound to, which the preview says — and nothing is posted until Post; the
service shows the headings and the list its own way. The preview says how long
the summary is against the most the service takes, and a summary longer than
that is refused with how long it is, and nothing is sent. Nothing about the
post is kept.
Earlier and Later move a period back or on — a whole month to the month, a whole year to the year, any other period by its own length — and Today shows today. The calendar below them — beside them on a wide window — shows a month, chosen by year and month, in which the arrow keys move a day or a week, Page Up and Page Down a month, and Home and End to the week’s ends; Enter or a click shows that day, and with Shift, the days from the first one shown to it. Whole month and Whole year show the month or the year the calendar shows. A period runs up to a year and a day.
Repositories
Where the server works, relative to what it changes: the repository it is in,
then the path within it, muted, as ~/src/api/cmd; origin’s host and path,
and Base, the repository pull requests merge into, beside it in a fork’s
clone; and the configuration files that apply there, the repository’s over your
home’s. The header carries the same place, briefly, as api/cmd, and opens
this section.
Worktrees are the repository’s working trees, as git lists them, each with the branch it has checked out — or the commit, when detached — and whether git keeps it locked, or finds its directory gone; Switch offers to switch to one, other than where the server works and one gone. With none to list, outside a repository, the list is left out.
Favorites are the directories you keep, each with what is there now — a repository and its origin, a directory in no repository, or one not there any more. Add to favorites keeps where the server works, Remove forgets one, and Switch offers to switch to it.
Go to a directory… (g, as in the terminal) opens a dialog for any other.
Its field lists the worktrees and favorites first, then the directories where
the server works; type a path — from where the server works, from your home
after ~, or from / — and it lists the directories in the one before the
last slash, narrowed as you type a name after it: those starting with it
first, then those holding its letters in order, the letters matched in bold,
and each repository marked. The arrow keys choose, Enter goes into a
directory or asks to switch to the place chosen, Backspace after a slash
goes up — from your home, on to the directory it is in, as in the terminal
— and the path above the field goes up further. Switch to, at the foot,
names the place highlighted and asks too. A hidden directory is listed once
the name typed starts with its dot, and a directory of more than a thousand
says that the first thousand are shown, as the server reports its limit, and
is listed again for the name typed; the list draws at most two hundred, and
says how many more match. The dialog stays open while a switch it asked for
runs, so its refusal is shown in it.
A switch is asked once more in the dialog, with Back to the list, then made:
the server wires the directory as it wired the first, and every section is read
again for it. A directory whose configuration did not load, or binds keys
workflow refuses, is refused rather than served on the defaults. The section you
are in, the views’ orders and narrowing and the Summary’s period stay; the issue
shown stays when it is a Jira issue, which is the same wherever you work. A page
that has not yet noticed a switch — another tab, say — has its writes refused
until it reads again, and a switch is refused while a write is being made. Under
--dry-run the switch and the favorites are held back with every other write,
and browsing still works.
Settings
The configuration file in effect, a section at a time, chosen from the list beside it — or above it, in rows, in a window narrower than 1024 px: Jira, Messaging, Forge and pull requests, Commits and branches, Taskwarrior, Terminal and keys and Advanced (timing and the store), which save together, then People and groups and Local data, which save as you change them. An edit stays as you move between sections, and each section’s tab marks how many of its settings are changed and not saved, or, once one is refused, how many are left to fix.
A bar stays in view below whichever section is shown. It says how many
settings are changed and not saved — a list counts once, however many of its
rows changed — with Discard, which puts every section back as it was
read, and Save changes, which writes the file; both are held while
nothing is changed. It says Saving…, then Saved. A setting refused is
marked beside itself, with why: a few are checked before anything is sent —
Jira’s address, the branch template’s {key}, the timings, the issue
trailer and the counts — and a save the server refuses names the settings
it refused, which are marked the same way. The bar then says how many are
left to fix and in which sections, and Show opens the first one’s section
with the focus on it. A save held back by those first checks goes to the setting
it was held back for, and leaves what the server refused marked. Changing a
refused setting takes its refusal away. Going to another section of the page
while settings are changed and not saved asks Leave without saving? first:
Leave drops the changes and goes, Stay keeps them.
Jira’s views and headers, messaging’s channels and the branch prefixes are
lists: Add a view (or a header, a channel, a prefix) puts a row in, and each
row’s Remove takes it out with the next save. A header’s name is fixed once
saved; to rename one, remove it and add it again. The keyboard part’s Rebind
keys lists every action the terminal binds, each with the key it is moved to
(ui.keys) and the default an empty one keeps; a key that clashes with another
where both work at once is refused when you save, as the terminal refuses it as
it starts. A credential is shown masked and kept as it is unless you type a new
one. Above its field it says where it is kept: Stored in the file; for the
Jira token, Kept in your keychain, for its host, Read from $JIRA_TOKEN (the
variable jira.token_env names) or Printed by a command you set; for Slack’s
client secret and refresh token, not in the file, where the macOS keychain may
keep them; for the forge token, not in the file, read from the environment or
the forge’s CLI when either has one — both come before a token the file keeps;
or Not set. Once you type one, it says it replaces the stored one when you
save. Beside each one the file holds — the Jira token, the forge token, Slack’s
client secret and refresh token, the webhook URL and each Jira header —
Remove… asks, then writes the file as it was read without it, leaving your
other edits in the form for Save changes; it cannot be undone, and removing
the client secret or the refresh token takes the access token made from them
too. A change to the forge part — its token, host, kind or CLI — applies at
once: the next call to the forge uses it, and the page names the forge it points
at, with no restart. A change to the messaging part applies to the next
announcement. A change to Jira’s address, its token or where the token is read
from (Read the token from your keychain, or jira.token_env or
jira.token_command in the file), its user or headers, or to whether this
repository’s issues are listed, waits until workflow restarts or switches
directory, as the part says: only then is Jira wired again. So does which view
those issues lead: they stay with the JQL the first view had, so editing that
JQL drops them from the first view, and putting another view first leaves them
leading the view that was first. The rest of the Jira part — its project, review
status, views and Markdown comments — applies at once. Slack’s user token is
three fields — Client ID, Client secret and Refresh token; on macOS a save
refreshes the token with them and keeps the secrets in the keychain rather than
the file, and where the file already keeps them it keeps what you type (see
Configuration). The access token and its
expiry have no field: workflow writes them. On macOS a Jira token you type goes
to the keychain item for the Jira address, never into a file, and Read the
token from your keychain is saved checked, so a repository whose file points
Jira at another address takes a token of its own here; a token the keychain will
not keep saves nothing. A change to the Taskwarrior part waits until workflow
restarts or switches directory, as the part says: workflow finds Taskwarrior as
it starts in a directory or switches to one, and until then the Tasks section
says to restart or switch directory rather than read Taskwarrior. What
the form has no field for is kept unchanged when you save: version,
jira.token_command, jira.token_env, and the Slack access token and its
expiry. The task program is shown but not typed into: workflow runs it, and
jira.token_command, as you, and reads the variable jira.token_env names, so
they change only in the file itself, and a save over the API that carries
another value for one is refused. Settings reads the file each time it opens,
and a save checks that the file has not changed since: when it has (edited on
disk, rewritten by workflow config init --force, or saved from another tab),
nothing is written, and Reload reads it again in place of your edits so you
can make the change again — the bar says so, with Reload. A save from
another workflow at the same moment (the terminal’s Settings, workflow config init, a Slack login) is waited for and then counted as such a change, through
a lock in workflow’s state directory; one that keeps the lock longer than ten
seconds has the save refused with another workflow is saving the
configuration, so nothing was saved; save again in a moment. An edit made by
hand in the moment between the check and the write, or any change on a system
that names no state directory, is still written over. When the file on disk is
not valid, Settings says so in place of the form, and workflow doctor says
what is wrong with it. A switch made while Settings is open, from another tab
or the terminal, reads the configuration again in place: when it reads the
same, byte for byte, and the same files apply where the server works now, as
Repositories lists them, your unsaved edits stay in the form. Otherwise,
a copy of the file in another worktree or clone included, the form shows the
file where the server works now, and says your unsaved edits were for the
directory left. Until both reads have answered, Save changes is held, so
a save never writes your edits over a file they were not made for.
Setting up
With no .workflow.json where the server works, Settings asks what
workflow config init asks instead of showing a form of defaults. First,
where the file goes: the repository, where it applies across it, or your home
directory, where it applies everywhere. Then Jira’s address and your personal
access token, typed into a field that shows nothing of it. With the OS
keychain wired (macOS), Keep the token in your keychain, out of the file is
offered, checked, for either file: the token goes to the keychain item for
Jira’s address, and the file holds "keychain": true, which reads it back.
Unchecked, the file keeps it, readable only by you. Last, a
Slack incoming webhook, saved unchecked; blank posts with your Slack user token
after workflow slack login. A blank address or webhook leaves that part out.
Write ~/src/api/.workflow.json — named for the file chosen — checks the
token with Jira first, saying Checking with Jira…. A check that does not
pass says why, beside the button, and writes nothing; Write it anyway keeps
the address and token unchecked — except an address that is not an https
address, or http to this machine, or that carries a username and password,
which is never kept. Once written, the server works with the file as it does
after a switch: the event stream reconnects, every section is read
again, and Settings shows the file with what was written said above it —
whom Jira knows the token as, that the keychain keeps it, and, for a file in a
repository git does not ignore, to add it to .gitignore. A server that could
not take the file up at once takes it up as Settings reads it again, or, when
it still cannot, says so and to restart workflow --web. So does a file made
there since, by hand or by workflow config init: reading the configuration
takes it up, and Settings shows it rather than the setup. A file already
there is never written over. A write still running, such as a git run started
in another tab, holds the setup back: it writes nothing, and says to set up
again once that write has finished. The token and the webhook go only to the
server on the loopback address, which takes them from no other page, and no
answer carries them back. Under --dry-run writing is held back, and the form
says so.
People and groups keeps what the announcement preview asks: a table of every
code owner decided on this repository’s forge host, then the branch’s owners not
decided yet, each with a choice of whom they are on Slack — not decided yet, not
on Slack, or a member of the configured channel (a team, a user group) — saved
as you change it. Forget… asks first, in place, and a forgotten owner is
asked about again at the next ready-for-review announcement. Groups for the
repository is a checkbox per user group in the workspace, kept with Save
groups; a ready-for-review announcement offers those groups to tag. Each saves
on its own, apart from the configuration, into kept.db, and the label kept is
the one Slack’s directory gives. A group already saved keeps its label, so one
Slack no longer lists, or a token that cannot read the groups, can still be kept
or unchecked, and clearing every group needs no Slack at all. A token without a
scope the choices need is named in a note. Under --dry-run the area says its
changes are held back and its controls are off.
Local data shows where workflow keeps what it learns between sessions and a
row for each database file: the cache (workflow.db) and the kept associations
and favorites (kept.db), each with its size and what it holds. It is read
each time Settings opens and saved apart from the configuration.
Remove cache… and Remove everything… each ask first, in place, with
Cancel and Remove; removing everything says that people and group
associations will be asked again and your favorites go with them, and People
and groups is read again to show them gone. What the removal did is said below
the buttons, and the listing is read again. A file another program holds open
fails the removal, and the area says why and reads the listing again, since a
file that could not be deleted after the rest were set aside may leave others
gone. A removal waits for a change to People and groups under way, and the other
way round. Under --dry-run the buttons are replaced by a sentence saying
removing is held back. It is the web’s workflow db-clean (see
Using workflow).
What stays in the terminal
The web covers the loop’s main line. These stay with the terminal interface, or the command line, by decision rather than by oversight; most are written down as ideas in FEATURES.md or UX.md:
- Offering a task change at the loop’s moments — starting the issue’s task when its branch is made or checked out, noting the pull request on it, completing it on a merge or a move to done; on the web those are the Tasks card’s and the Tasks section’s buttons, pressed when you choose.
When a request fails
A failed request says why beside the button that made it, in words meant for
you, and the button is there to try again; a read that fails says why above
Try again. While a section reads, a line beginning Reading says what.
When the words do not say enough, Questions and
troubleshooting has what to do for the common ones.
Behind those words, the API answers a
failed request with an RFC 9457 problem details object whose code a script
can rely on, a request presenting no session among them (401,
unauthorized); only the loopback, same-origin and --dry-run guards, which
refuse a request before it reaches the API, answer in plain text. Web API
errors lists the codes.
Scripting the API
These requests answer what a section shows, for a script on the same
machine: eight reads, and the Repositories section’s three writes — a PUT
that switches where the server works, and a PUT and a DELETE on one path
that keep or forget a favorite. The page takes the first four reads from its
stream, and makes the others as its sections need them.
api/openapi.yaml
describes each answer’s fields, and every other request the API serves.
| Request | Answers with |
|---|---|
GET /api/branch | The checked-out branch: its base, its upstream, how far it is ahead or behind, and its commits |
GET /api/changes | The working tree’s changes |
GET /api/review | The branch’s pull request and its CI |
GET /api/messaging | The messaging service, and where and as whom an announcement would post |
GET /api/activity | What you did from one day to another, or on the previous working day, nested by year, month, day and hour, with the Markdown to copy |
GET /api/repositories | Where the server works — the directory, its repository and the path within, origin and the configuration files — and your favorite directories, each with what is there now |
PUT /api/repositories/here | Switch the directory the server works in; refused while a write is in flight |
PUT / DELETE /api/repositories/favorites | Keep a directory as a favorite, or forget it |
GET /api/directories | The directories in one, or those whose names start with a prefix, to browse for one to switch to; a listing cut short at its limit gives that limit as truncated_to |
GET /api/tasks | Your pending Taskwarrior tasks, most urgent first, waiting ones included, with the active context and whether a sync backend is set |
Every request presents the run’s session, the part of the printed address
after #session=, as Authorization: Bearer <session>; one without it is
answered 401 with code unauthorized. The event stream, which a browser’s
EventSource opens with no header of its own, also takes it as ?session=.
session=… # the part after #session= in the address workflow --web printed
curl -s -H "Authorization: Bearer $session" http://127.0.0.1:13579/api/reviewGET /api/repositories’s answer needs no server: workflow repositories --json prints the same object from the directory it runs in, and workflow summary --json prints what GET /api/activity answers for the same period.
POST /api/activity/post posts the Summary: from and to, the period it
is of, text, its Markdown as GET /api/activity wrote it or as it was
edited, and channel, or none for the configured one or a webhook’s own. The
server renders the Markdown for the service as it posts it and keeps nothing
of the post; it answers where the text went, in destination.
curl -s -H "Authorization: Bearer $session" http://127.0.0.1:13579/api/activity |
jq '{from, to, text}' |
curl -s -H "Authorization: Bearer $session" -H 'Content-Type: application/json' -d @- \
http://127.0.0.1:13579/api/activity/postThe reads answer under --dry-run too, and the writes are refused there, as
every write is. When git or the forge fails, the branch, changes and review
reads answer a problem, so a script can
tell a failure from nothing to show; the event stream carries the same
problem beside the panel it emptied, in the snapshot’s problems, and a CI
read that failed in the review’s ci_error. The stream’s first message may
be a seed event instead of a snapshot: the view’s issues as the store
last kept them, sent before anything is asked of the network; a script that
reads snapshot events alone can ignore it. A service that is not set up —
a Jira or forge token missing, a base remote that names no forge — is a
problem whose code is not_set_up, its detail saying how to set it up, so
a script tells it from a refusal; /api/activity marks such a source’s
state not_set_up, apart from failed. The
tasks read answers available: false and why, never a problem, when there is
no Taskwarrior to ask; a Taskwarrior that is there but fails the read answers
a problem.
The Tasks section’s writes are POSTs beside that read: /api/tasks to add a
task, /api/tasks/track to track an issue, /api/tasks/undo,
/api/tasks/sync, and start, stop, done, annotations and modify
under /api/tasks/{uuid}/. Each answers the task list as it stands after the
write, and a task Taskwarrior changed nothing on answers 409. A done of a
task linked to an issue also answers that task as it stands done, in done,
since the list no longer holds it.
GET /api/hooks lists the hooks lefthook configures: in runnable, those a
run by hand can stand in for, and in git_only, those only git runs, each
with the reason. POST /api/runs with {"kind": "hook", "hook": "pre-push"} runs one runnable names — or rebase, amend, or fixup
with the commit to fix up — and answers newline-delimited JSON as the run
goes: the run as it starts, a line for each line its program writes, and
the run as it ended, with its state and outcome. A hook runnable does
not name is refused with a 422. DELETE /api/runs/current stops it.
curl -sN -H "Authorization: Bearer $session" -H 'Content-Type: application/json' \
-d '{"kind":"hook","hook":"pre-push"}' \
http://127.0.0.1:13579/api/runsPeople and groups read GET /api/people and GET /api/repo-groups, and
write with PUT to each and DELETE /api/people?owner=; the choices come
from GET /api/slack/members and GET /api/slack/groups, which answer a
missing scope as a 200 naming it. GET /api/announcement?channel= checks
an owner not yet linked against that channel’s members. POST /api/announce
takes mentions: users, the people the preview showed tagged, and
groups, the user groups checked. The linked owners it tags are read from
what is kept, never from the request, and a post whose linked owners are not
users is a 409. It also takes edited_text, posted in place of the
composed announcement beside text, the one the edit began from, and
when: ci_passes, which holds it until the CI passes and answers 202, with
replaced_pull when it replaced another pull request’s;
DELETE /api/announce/queued stops a held one, and each frame of
GET /api/events carries it as queued_announcement, with its id, a new
one each time one is held afresh, its state and, while it waits,
waiting_on. The frame’s review.announced reads posted, unconfirmed,
unknown or none. Two announcements asked at once post once, the other
answered 409; while a held one is being posted, announcing, holding another
or stopping it is a 409 too, and a stop refused changes nothing.
The issue writes sit under /api/issues/{key}/: GET and POST transitions
list the status changes with the fields each needs and make one,
PUT assignee assigns it, and POST worklog logs work on a Jira issue.