Scope and collisions
A card’s scope is the list of files its work may change. It does two jobs: it tells the agent where its edges are, and it lets Docket keep two cards from changing the same file at the same time.
Scope is a boundary
Section titled “Scope is a boundary”The brief an agent is given lists the card’s scope and says what to do when the work needs a file that is not on it:
ask for the file first, then edit it. Asking is claim_files.
claim_files takes exact file paths. If no other card being worked on holds them, they are added to the card’s scope
and the agent carries on. If one does, the agent is told which card and can wait, or make its card depend on that one.
The point of asking before editing is that backing out is still free.
When a card is finished, Docket compares the files git shows as changed with the files the card held. Files that were changed and never held are recorded on the card.
Exact paths and patterns
Section titled “Exact paths and patterns”A scope entry is either an exact path, such as app/billing/proration.ts, or a pattern with a * in it, such as
app/billing/**.
Name the files you know the work will change. Use a pattern for the rest.
Two cards, one file
Section titled “Two cards, one file”Two rules apply, and both are on for a new project.
A file being worked on is held. While a card is being done, the exact files in its scope are held. Another card that names one of them is not ready, and a claim on it is refused with the name of the card that holds the file.
Cards that share a file are put in order. Whenever a card’s files change (when it is made, when its scope is
edited, when it takes a file with claim_files, and when it finishes) Docket looks for other cards that name one of
the same exact files. If one of the two has been started, the other is made to depend on it, and waits until it is
done and merged. The card that starts first goes first. Two cards that have not started are not ordered against each
other, since nothing can collide yet.
The agent is told each time this happens, with the cards and the files, and how to undo it.
Why merged, and not just done: the second card branches from your main branch. If the first one’s pull request is still open, the second would start from code that does not have the first one’s changes, and the conflict would only show up at the merge.
Once a card is done, the files it holds are the ones git shows it changed, not the ones it predicted.
If an order is wrong, unlink_cards removes it and Docket does not add it back.
Turning the rules off
Section titled “Turning the rules off”Both rules are settings of the project. There is no control for them on the board or among the tools yet.