332 lines
14 KiB
Markdown
332 lines
14 KiB
Markdown
---
|
|
name: worklane-admin
|
|
description: Set up and repair a worklane board itself, whatever it tracks: design and annotate the tag vocabulary with `worklane tags`, retire or rename a tag, and fix a board whose files and fields disagree, such as a ticket missing from `ls`, a duplicated id, a stray temp file or a move that will not go through. Use when the subject is the board's own configuration or health. Not for filing, working or reviewing a ticket, and not for priorities, due dates or campaigns.
|
|
---
|
|
|
|
# Administering a worklane board
|
|
|
|
For "set up a board for this", "what tags should this board have", "add a tag", "what
|
|
does this tag mean", "the board is in a weird state", "this ticket has gone missing".
|
|
The subject is the board itself: the vocabulary it files against, and the parts that can
|
|
come apart.
|
|
|
|
The CLI is the `worklane` skill: the statuses, how a ticket is addressed, which command
|
|
owns which field. Read it too.
|
|
|
|
**This is not `worklane-plan`.** That skill grooms the work: priorities, due dates,
|
|
retagging tickets, campaigns. This one decides what the tags *are* and puts the board
|
|
back together. The line between them is the tag section: designing and annotating the
|
|
vocabulary is here, applying it across tickets is there.
|
|
|
|
## A board is not only for software
|
|
|
|
Everything below holds for a board tracking a product strategy, a house move or a term's
|
|
teaching, and the worked examples say so. What changes between domains is the tags, never
|
|
the shape. Nothing in worklane knows what your tickets are about.
|
|
|
|
Two things you do not get to configure, whatever the board is for:
|
|
|
|
- **The four statuses.** `backlog`, `committed`, `reviewing`, `done`, in that order, one
|
|
step at a time. There is no way to rename them or add a fifth. If a board wants a
|
|
waiting-on-someone-else state, that is a tag, and the ticket stays in `committed`.
|
|
- **The fields.** Priority 1 to 5, Due, Owner, Tags, Campaign. A board that wants a
|
|
concept these do not cover expresses it as a tag or a campaign, not as a new field.
|
|
|
|
So the tag vocabulary is where a board is fitted to its subject, and it is most of this
|
|
document.
|
|
|
|
## Starting a board
|
|
|
|
```
|
|
worklane init # in the directory the board belongs to
|
|
```
|
|
|
|
Which directory decides which board. Commands walk up from the working directory to the
|
|
nearest `.worklane`, so a board in `~/house` answers every `worklane` run from anywhere
|
|
under `~/house` and nowhere else.
|
|
|
|
`init` makes the four status directories, the campaigns directory and an empty `tags.md`.
|
|
Run on a board that already exists it prints a line and changes nothing, which is what
|
|
makes it safe to run when you are not sure.
|
|
|
|
Then declare the vocabulary before the tickets pile up. Tags applied for months are far
|
|
harder to change than tags agreed once, because changing one means rewriting every ticket
|
|
carrying it.
|
|
|
|
## Designing a tag vocabulary
|
|
|
|
A tag is a word a ticket carries so the board can be cut by it later. `worklane ls --tag
|
|
kitchen` is the whole payoff, so the test of a good vocabulary is whether the cuts it
|
|
allows are cuts anyone wants.
|
|
|
|
### Work in axes
|
|
|
|
An axis is one question every ticket on this board can answer, with a small closed set of
|
|
answers. Pick two or three axes and keep them apart. Nearly every vocabulary that goes
|
|
bad is one where two axes were mixed into one pile of words.
|
|
|
|
A software tool:
|
|
|
|
| Axis | Answers |
|
|
|---|---|
|
|
| Kind | `feature`, `bug`, `chore`, `docs` |
|
|
| Area | `cli`, `tui`, `api`, `build` |
|
|
|
|
A product strategy:
|
|
|
|
| Axis | Answers |
|
|
|---|---|
|
|
| Kind | `research`, `decision`, `experiment`, `writeup` |
|
|
| Audience | `enterprise`, `self-serve`, `internal` |
|
|
|
|
A household:
|
|
|
|
| Axis | Answers |
|
|
|---|---|
|
|
| Kind | `repair`, `errand`, `admin`, `cleaning` |
|
|
| Room | `kitchen`, `garden`, `garage`, `car` |
|
|
|
|
Same shape, nothing in common. Derive the axes from the questions somebody will actually
|
|
ask this board, not from a template: if nobody will ever ask "show me everything in the
|
|
garage", `garage` is not earning its place.
|
|
|
|
### The rules
|
|
|
|
- **A tag is for kind, not for state.** State is the status directory. A `doing` tag
|
|
beside `committed`, a `blocked` tag beside a `blocked by` relation, a `done` tag at all:
|
|
each is a second copy of something the board already knows, and the copy is the one that
|
|
goes stale.
|
|
- **A tag is not a goal.** Everything for one outcome is a campaign, which has a title, a
|
|
description and a state derived from its members. `worklane campaign` owns that;
|
|
`worklane-plan` decides what belongs in one.
|
|
- **A tag is not a field.** No `p1` beside Priority, no `alice` beside Owner, no `august`
|
|
beside Due. The field is the writer and the tag will disagree with it.
|
|
- **A tag is not a person.** Owner is a field, and `chown` writes it.
|
|
- **Two axes, not two words for one thing.** Before adding a word, say which axis it is
|
|
on. If it does not fit one, either it is a new axis, which is a decision, or it is a
|
|
private note, which is not a tag.
|
|
- **Around a dozen tags, up to twenty.** Past that nobody remembers the vocabulary, so
|
|
they invent a near-duplicate instead of reusing what is there. Fewer, broader tags beat
|
|
a long tail nobody can recall.
|
|
- **Singular or plural, pick one and keep to it.** `bug`/`bugs` and `chore`/`chores` are
|
|
the commonest way a board ends up with two words for one idea.
|
|
- **Case matters.** `Bug` and `bug` are two tags to `--tag`, to `tags` and to the colour
|
|
a card is drawn in. Lowercase everything unless there is a reason.
|
|
|
|
### How many tags per ticket
|
|
|
|
One per axis is the target: a ticket is one kind of thing in one area. A ticket that wants
|
|
three areas is usually two tickets, and a ticket with no tag at all is invisible to every
|
|
question asked by tag.
|
|
|
|
## Annotating a tag
|
|
|
|
```
|
|
worklane tags # every tag, its count and what it means
|
|
worklane tags add kitchen --annotation "..." # declare one, and say what it means
|
|
worklane tags set kitchen --annotation "..." # change what it means
|
|
```
|
|
|
|
`.worklane/tags.md` holds one section per declared tag, the tag as the heading and its
|
|
annotation under it. It is what a person opens to find out what the board means by a word,
|
|
and it is what an agent reads before choosing one.
|
|
|
|
**Declaring a tag tags nothing, and tagging a ticket declares nothing.** The two lists are
|
|
separate on purpose: the counts come from what the tickets carry, `tags.md` records what
|
|
the board agreed on, and the difference between them is the thing worth looking at. A tag
|
|
carried by tickets but never declared is a word somebody invented in a hurry.
|
|
|
|
`worklane tags` reports both, as the tag, a tab, the count, and a tab and the annotation's
|
|
opening line for a tag that is declared. So the two cases worth finding read off the
|
|
listing: a tag at a count of zero is declared and nobody has reached for it, and a tag with
|
|
no annotation column at all is carried and was never declared.
|
|
|
|
### What an annotation has to say
|
|
|
|
The definition is the easy half and does the least work. What stops drift is the boundary
|
|
against the neighbouring tag, so write that.
|
|
|
|
Worthless, because nobody was ever unsure of this:
|
|
|
|
```
|
|
worklane tags add bug --annotation "Bugs."
|
|
```
|
|
|
|
Useful, because it answers the question somebody was actually about to get wrong:
|
|
|
|
```
|
|
worklane tags add bug \
|
|
--annotation "Behaviour that contradicts what the tool says it does, reproducible from a described state." \
|
|
--annotation "" \
|
|
--annotation "Not for something missing. A gap is a feature, however obvious the gap is."
|
|
```
|
|
|
|
The same for a household board:
|
|
|
|
```
|
|
worklane tags add repair \
|
|
--annotation "Something that worked and now does not." \
|
|
--annotation "" \
|
|
--annotation "Not for an improvement to something that works, which is a project, and not for a thing that needs replacing rather than fixing."
|
|
```
|
|
|
|
Repeat `--annotation` for more lines, and pass an empty one for a paragraph break. Three
|
|
lines is plenty: a definition, then the boundary.
|
|
|
|
Write an annotation for every tag, including the obvious ones. The obvious tags are the
|
|
ones two people quietly disagree about.
|
|
|
|
### Traps
|
|
|
|
- `tags add` refuses a tag that is already declared, and `tags set` refuses one that is
|
|
not. Each names the other, so the refusal tells you which you wanted.
|
|
- A tag cannot contain a comma, because a comma is what separates one tag from the next in
|
|
the Tags field. Surrounding spaces are trimmed.
|
|
- A tag you have declared and never applied lists at a count of zero. That is not a fault;
|
|
it is the file and the board disagreeing, which is the state that tells you the
|
|
vocabulary has not landed yet.
|
|
- Nothing removes a declaration. There is no `tags rm`, so a tag declared in error stays
|
|
in the file with whatever its annotation says. Say it is retired in the annotation.
|
|
|
|
## Changing the vocabulary later
|
|
|
|
### Renaming a tag
|
|
|
|
There is no rename. The tag is the key, so it means rewriting the Tags field of every
|
|
ticket carrying it, one at a time:
|
|
|
|
```
|
|
worklane ls --tag bugs --ids # every ticket carrying the old word
|
|
worklane show 1b78a24 # read the whole Tags field of each
|
|
worklane set 1b78a24 --tags bug,cli # restate all of them, with the new word
|
|
worklane tags add bug --annotation "..."
|
|
```
|
|
|
|
**`--tags` replaces the whole field.** Restate every tag the ticket should keep or the
|
|
ones you leave out are gone, with no undo. This is the most destructive command on the
|
|
board. Read the ticket's current tags before writing, never from memory, and run
|
|
`worklane tags` before and after: a count that moved where nothing was meant to change is
|
|
a tag lost to that rule.
|
|
|
|
Propose the whole list of edits and wait for approval before applying any of them, the way
|
|
`worklane-plan` requires for a sweep. The reason is the same: nothing records what a field
|
|
held before you wrote to it.
|
|
|
|
### Retiring a tag
|
|
|
|
Take it off the tickets the same way, then leave the declaration saying it is retired and
|
|
what replaced it. A tag with a count of zero and an annotation pointing elsewhere is a
|
|
better answer than a word that simply vanishes, because the next person will otherwise
|
|
reinvent it.
|
|
|
|
## Repairing a board
|
|
|
|
Every repair here has been run against a real board. Work by symptom.
|
|
|
|
**The rule that does not bend: do not edit a ticket file.** The filename, the `Status`
|
|
field and the directory have to agree, and the commands are what keep them agreeing. The
|
|
two exceptions below are files no command owns, and they are marked as such.
|
|
|
|
### A ticket has vanished from `ls`
|
|
|
|
`worklane ls` leaves `done` out of its listing, though it still counts it at the top. So
|
|
first check `worklane ls done`. If it is there and should not be, its file has been moved
|
|
into the wrong directory by hand or by a restore.
|
|
|
|
`mv` reads the current status from the *directory*, so one move puts both halves right:
|
|
move the ticket to the status it belongs in and the field travels with it.
|
|
|
|
```
|
|
worklane mv 1b78a24 --status reviewing -f
|
|
```
|
|
|
|
If the file is where it belongs and only the `Status` field inside is stale — a hand move
|
|
that forgot the field, or a half-finished restore — name the directory the file actually
|
|
sits in: a move there finds the field disagreeing with the directory and rewrites just
|
|
the field, reporting the correction instead of refusing as a no-op.
|
|
|
|
```
|
|
worklane mv 1b78a24 --status done
|
|
```
|
|
|
|
That repair changes only the field: no stamp is written and no history entry either,
|
|
because the work went nowhere. Check either repair with `worklane show 1b78a24`, whose
|
|
`Status` line is read from the file rather than from where it sits.
|
|
|
|
### A command says the id matches several tickets
|
|
|
|
```
|
|
Multiple tickets found matching 'bf2dc18':
|
|
1. (bf2dc18) Alpha [backlog]
|
|
2. (bf2dc18) Alpha [done]
|
|
```
|
|
|
|
The same file exists in two status directories, usually from a copy or a half-finished
|
|
restore. The ticket is now unaddressable: every command resolves before it acts, so `show`
|
|
and `mv` fail the same way and cannot be used to fix it.
|
|
|
|
**File exception.** Read both with `cat`, keep the one whose `Status` field agrees with
|
|
the directory it is in, and delete the other. If neither agrees, keep either and repair it
|
|
as above. Then confirm with `worklane show`.
|
|
|
|
### A move is refused by a blocker
|
|
|
|
```
|
|
Cannot move 'Beta' while it is blocked by:
|
|
...
|
|
Use --force (-f) to move it anyway.
|
|
```
|
|
|
|
Working as intended: a ticket cannot advance while something it waits on is unfinished.
|
|
Finish the blocker, or use `-f` if the dependency is no longer real. Note that the
|
|
relation stays on the ticket and will refuse the next move too, and there is no way to
|
|
take a relation off, so `-f` is the answer every time until the blocker is done.
|
|
|
|
If the message says `is blocked by X, which is not on the board`, the blocker has been
|
|
deleted. That is a warning rather than a refusal and the move goes through.
|
|
|
|
### `show` renders `_missing_`
|
|
|
|
A relation or a Campaign field naming something the board no longer holds. Harmless to
|
|
read and impossible to clear, since `relate` only adds and `assign` only moves a ticket
|
|
between campaigns that exist. For a campaign, `worklane assign <a-real-campaign> <ticket>`
|
|
overwrites it. For a relation, leave it.
|
|
|
|
### A status is missing from `worklane ls`
|
|
|
|
The count list at the top of `ls` names every status directory it found, so a status that
|
|
is absent from it has had its directory deleted. Nothing errors until something tries to
|
|
move a ticket there, which then fails with a raw file error.
|
|
|
|
**File exception.** `worklane init` will not repair it, since it refuses on a board that
|
|
already exists. Recreate the directory:
|
|
|
|
```
|
|
mkdir .worklane/reviewing
|
|
```
|
|
|
|
### A `.wl-*.tmp` file in `.worklane/`
|
|
|
|
The staging file for a write that was killed part way. Every write stages here and renames
|
|
into place, so a leftover means the write did not finish; nothing reads these and no
|
|
listing shows them.
|
|
|
|
**File exception.** Delete it. Then check the ticket it names with `worklane show` and
|
|
redo whatever the interrupted command was.
|
|
|
|
### Nothing works and the error names `.worklane`
|
|
|
|
Check where you are. Commands resolve the nearest `.worklane` at or above the working
|
|
directory, so running from the wrong directory addresses another board or none. `worklane
|
|
ls` from where you think the board is, is the fastest way to find out.
|
|
|
|
## What this skill does not touch
|
|
|
|
- **Priorities, due dates, campaign membership and retagging sweeps.** That is
|
|
`worklane-plan`. Deciding the vocabulary is here; applying it across the board is there.
|
|
- **Filing a ticket, working one, moving it through the statuses.** That is the `worklane`
|
|
skill.
|
|
- **Judging whether a finished ticket is really done.** That is `worklane-review`.
|
|
- **The content of a ticket.** A description or an acceptance criterion that is wrong is
|
|
the author's, and the answer is a comment on that ticket.
|