Branches and diffs

Branches and diffs

A branch is a change request. Every draft lives on one, whoever or whatever made it.

Naming

One branch per topic, named draft/<who>/<slug>:

draft/ada/rewrite-install-guide
draft/agent/openapi-v3-fields

The name is not decoration. It is what a reviewer sees in the pull request list, and it is how you tell an agent’s branch from a person’s.

Staged, committed, published

Three states, and the difference between them matters:

State	Where it is	Who can see it
Staged	Not in git yet	You, and the writer
Committed	History, on a branch	Anyone with the repository
Published	Merged to the default branch	Every reader

A staged change is reversible with no trace. A commit is history. A merge is publication.

Reading the diff

The diff is per page and per block. It shows what a reader will see change, not which bytes moved.

For a change made by an agent, the diff is the review. This is the step the product is built around: an agent may draft and commit, and publishing is not offered to a machine at all.

Warning

Do not merge an agent’s branch without reading it. The whole editorial model is that a person read the diff, and a merge is the moment that stops being optional.

Conflicts

If the same page changed on the default branch while your branch was open, Staleless detects the mismatch and refuses to overwrite. You get the diff and three choices: take yours, take theirs, or merge by hand.

Nothing is silently overwritten. A revision mismatch is a question, not an outcome.

Two writers, one page

While two people edit the same page in the writer, each sees that the other is there. The second save is checked against the revision the first produced. A blind overwrite is not possible.

Working from your own editor

A branch is an ordinary git branch. Check it out, edit the Markdown, commit, and push. The writer reads the branch and shows the change.

Run the linter before you push:

npx staleless lint docs

It needs no token and no network, so it works from a fork. See the CLI.