The life of a card

A card is in one of these states.

State	What it means
To do	Waiting. It may or may not be ready to start.
Doing	An agent has claimed it and is working on it.
Done	The agent has finished and reported.
Orphaned	It depends on a card that was deleted, and needs repairing.

Merged is not a state. It is a fact the board learns about a card that is done, and it is the one that matters most. More on that below.

Claiming

An agent starts a card by claiming it, with claim_next. A card has one holder: once it is claimed, nobody else can claim it.

The claim comes with a claim token, a number. The agent has to give it back with every later call about that card: add_note, claim_files, finish_card and release_card. The token is what lets Docket refuse a report from an agent that no longer holds the card.

The lease

A claim lasts 30 minutes from the last thing the agent did with it. Leaving a note, taking a file, or any other call that carries the token starts the 30 minutes again, so an agent that is working keeps its card for as long as it works.

An agent that has stopped, because it crashed or its session ended, loses the card when the 30 minutes run out. The card goes back to to do and can be claimed again. If the first agent comes back later, its token is refused and it is told to claim again.

Three ways a card leaves doing without being finished:

The agent gives it back with release_card and says why.
The lease runs out.
You take it back from the board, with Take it back on the card.

In all three the card returns to to do.

Finishing

finish_card moves the card to done. The agent is expected to have run the card’s acceptance command first and to report what happened, along with notes for whoever works on the cards that depend on this one. Those notes are the handoff: the next agent’s brief includes them.

Docket records two kinds of fact with a finish, and keeps them apart:

Reported is what the agent said: how the command went, its notes, the files it says it changed.
Verified is what the adapter read from git: the branch and the commit, the files git shows as changed, whether the branch has been pushed, and the pull request’s address.

The board shows which is which.

Why done is not merged

Done means the agent says it has finished. That is a proposal. Whether the work is any good, and whether it goes into your main branch, is still up to you.

So Docket tracks the merge separately. When commits on your main branch carry the card’s reference in a trailer, the card is merged:

Prorate a seat added in the middle of a cycle

Card-Id: APP-215

The adapter looks for this each time an agent calls claim_next, get_card or list_cards. It reads your checkout’s copy of the main branch, so a merge is seen once that checkout has fetched it. A commit without the trailer cannot be matched to a card, and the card stays “done” with no merge seen.

It matters for more than neatness. When two cards change the same file, the second waits for the first to be merged, not just done: started any earlier, it would branch from a main branch without the first one’s work. See Scope and collisions.

Orphaned

A card becomes orphaned when a card it depends on is deleted. It cannot be claimed until the dependency is dealt with: remove it with unlink_cards, or point the card at different work with link_cards. It then goes back to to do by itself.

list_cards with status: "orphaned" shows them.