74 lines
6.4 KiB
Markdown
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
|
|
|