Files
worklane/docs/shared-boards.md
T

6.4 KiB

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