Where a value lives¶

The board is the one truth. Each forge and the GitHub Project is a mirror of it: a copy of some of its values, on GitHub or GitLab. Every write a mirror accepts ends in a recorded agreement, the value both sides last held. This page says where each value lives, and what happens when you switch a mirror on, off, or round. Each case names the test that proves it. Sync gives the run's rules, Forges what each forge needs, Datastores where the board is kept.

The board and its mirrors¶

                     the board: issues, people, fields as ns:value
                     labels, in one datastore (board.datastore)
                          |
         ┌────────────────┼────────────────┐
     a GitHub forge    a GitLab forge    the GitHub Project
     its issues        its issues        its columns

• The board's value is the truth. A field's value is a label in the board (status:ready, ADR 0004). A pull writes a mirror's value into the board, and from then on the board holds it as its own. A mirror can be where a change starts; it is never the truth.
• The board is your clone's. Two clones meet through git (origin, a fetch, a push), not through a forge. Three repositories that share one forge have three boards; the forge is where they meet.
• The datastores are homes, not levels. git, PostgreSQL and Markdown hold the same board; a clone has one. The forge-only datastore is the exception: a board kept only as the forges' copy, with no store of its own (ADR 0002, section 4).
• The mirrors are peers, not levels. A forge and the Project each compare the board with themselves, never with each other. GitLab has no Project, so a field the Project holds on GitHub is a label on GitLab. One git board sync runs git pull, the forges, the Project, then git push.

The three decisions¶

Where a value is follows from three decisions, and from nothing else.

• Which forges. With no table, the forges are the projects origin names. Writing one table turns that off. A forge found this way never starts creating issues silently: a first sync with a forge, or 50 creations or more, waits for consent (--allow-create, the Sync page's checkbox).
• Which way. both pulls and pushes. pull makes a read-only mirror: the run reads it, and writes nothing there. push makes a backup: the run writes to it, and pulls nothing; an edit made there is put back to the board's value at the next run, and counted.
• Where a field lives. On a forge, a field's home is its mapping's to, else its type's default: a label, the due date on GitLab, the assignees, sub-issues on GitHub, the milestone. On GitHub with a Project, the fields [github-project] fields names live in the Project's columns, not in labels. project configure and the Project page write that list with the Project. A table without it holds the default seven (status, prio, mod, est, sprint, moscow, milestone), and the Project page says the file does not state them yet. Settings › Fields shows the resolved home of each field on each forge.

The agreement, and the two conflict rules¶

For each field, a run compares three values: the board's, the mirror's, and the agreement. On a forge, the agreement is a seen record in the forge's sync entity (Last seen); on the Project, it is the issue's git-board:<owner>/<number>:<field> metadata.

• Neither side changed: nothing moves.
• One side changed: that side's value goes to the other.
• Both changed, differently, on a forge: the later change wins, the forge's at the same second. A forge's change is already public.
• Both changed, differently, on the Project: the field is held on both sides, named on the Conflicts page, until a person keeps one side (git board project resolve, or the page's buttons). The Project never wins by itself.
• Labels are sets, compared label by label, so two sides that add different labels both keep theirs.
• An accepted write is recorded at once, so a run that stops loses nothing and never writes the same change twice (Crash recovery).

The reversibility guarantees¶

1. An agreement survives its mirror. Turn a forge or the Project off, and its records stay. Turn it on again, and a sync moves only what changed since.
2. A held label comes back. When a field stops living in the Project, it flows to GitHub as a label again, and the board's own change wins over a stale copy.
3. A home moves only when you ask. Changing a field's home moves no value by itself. git board sync --migrate <field> says what it would set and remove, then does it.
4. A Project conflict is never won by itself. It waits for a person.

Switching, case by case¶

The use cases¶