Files
worklane/docs/shared-boards.md

74 lines
6.4 KiB
Markdown

# Boards on Disk
The two board layouts, the pointer file, and how a board is found from a working directory.
## Shared Boards
- **A project's board is on one of two layouts, and `src/board.rs` is the whole of the
second one.** The local layout is the `.worklane` directory a project has always had.
The shared layout answers `.worklane` being gitignored and not a git repo so a clone
elsewhere has no board: the project commits a `.worklane.toml` naming its board by
uuid, one boards repo is cloned once per machine, and `.worklane` in the project
becomes a *symlink* into it. The symlink is the point: with no `.worklane` directory
`cat .worklane/backlog/*.md` and `ls .worklane/reviewing` would stop working, and that
is the belief the whole file format exists to serve. Because the link is transparent,
`find_worklane_dir` gains no resolution code at all (c6a61b4 AC 14).
- **The machine config lives at `$XDG_CONFIG_HOME/worklane/config.toml`** (default
`~/.config`, empty counts as unset). It carries a `[boards]` section holding the *url*
of the boards repo and an optional `dir` overriding where the boards directory sits —
the config is *this machine's* answer, and the pointer carries no server address, so a
client repo never holds an internal hostname. The boards directory itself defaults to
`$XDG_DATA_HOME/worklane/boards` (`~/.local/share` without it).
- **The pointer is `.worklane.toml`, committed at the project root:**
`[worklane] board = "<uuid>"`, and nothing else. Read and written by `read_pointer` /
`write_pointer`. `write_pointer` leaves a pointer that already names the same board
alone — it is a committed file and rewriting it writes nothing new, which is what keeps
"init symlinks it and creates nothing" true for a fresh clone.
- **A board directory is `<uuid>_<slug>`, named after the ticket files.** The slug is
`util::slug` of the project's directory name, and resolution (`resolve_board`) is a
uuid prefix match, the bargain the ticket filenames already make: the directory stays
readable to `ls`, identity is stable, and renaming a board breaks no committed pointer.
- **The decision table is `decide_init`, one match.** The reason it is a table rather
than a fallback is that no branch may fall through into creating a board, so each row
returns its own outcome. The rows:
- no pointer, no `[boards]` config → local `.worklane`, exactly as `init` always made
it (AC 12);
- no pointer, config present → create the board, write the pointer, symlink `.worklane`
to it (AC 4);
- pointer present, board found → symlink it and create nothing (AC 5);
- pointer present, board absent → refuse. A committed pointer is proof the board exists
somewhere, so a missing board is an unsynced machine, and creating a second board
there produces two boards with one name and a manual merge — the worst outcome in the
design. The refusal says so and names `init --create` as the only way to make one
(AC 6/7). The fetch-and-look-again half of the ticket is deferred: nothing pulls the
boards repo yet, and the refusal names it rather than doing it. **`--create` is the
`create` field on `Command::Init`**, the escape hatch under that row;
- the boards directory itself missing → a distinct refusal saying the boards repo is
not cloned here (AC 8);
- the correct symlink already in place → no change, nothing written (AC 9);
- a symlink to a *different* board → refuse rather than repoint it: changing what a
project is on without asking is how two machines come to disagree about the work
(AC 10);
- a symlink that dangles → refuse rather than replace it without asking;
- a real `.worklane` directory under a pointer → refuse and name the adopt path
(aa80db4), never walk over it (AC 11).
- **The three symlink states are told apart by `classify_worklane`:** `Absent`,
`RealDir`, `Symlink`, `Dangling` and `NotADirectory`. The `Symlink` comparison is
canonicalized, the `Dangling` one is lexical (a dangling link cannot be canonicalized)
and checks for the relative spelling this tool writes or the absolute board path.
- **The symlink target is relative** to the link's own parent, so it uses no home
directory path and the link is portable in that limited sense; an absolute target
appearing anywhere is how a home directory leaks into a write. Because a relative
target depends on how deep a repo sits, `init` still runs once per project per machine,
which is the price of transparent access.
- **Everything under `.worklane` is layout-agnostic.** `create_board_contents` makes the
same status directories, `campaigns/` and `tags.md` for a local and a shared board,
and every reader below `find_worklane_dir` works through the link unchanged.
## Finding the Board
- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward
- Anything other than `NotFound` from `symlink_metadata` is an error rather than an `Absent`. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place
- The dangling failure **names the target and says the boards repo may not be cloned**, and deliberately does not say to run `worklane init`. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem
- **A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target.** `.worklane/backlog/*.md` has to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on
- A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today