Versions claimed up front

Why claim a version#

Two pieces of work started side by side on one repository would each take "the next version" when they began: the same one. The second found out only when it conflicted on its way in. Instead, whoever starts the work, you or your AI coding assistant, asks the Steward for its version first, once the branch is known.

Claim one#

In a terminal:

node $HOME\.steward\app\src\cli.ts claim-version example-app --branch feature/search --for "search in the toolbar"

It answers with the version, and the files to set it in:

Example App 1.4.3: yours. Set it in package.json, package-lock.json.

• The repository can be its id, its name, or owner/name: one the Steward looks after, one Reeve found on this PC, or the clone the command runs in.
• --branch is the branch the work is on. The same branch asking again gets the same version ("claimed already for this branch").
• --for says what the work is, for whoever looks at the claims.
• --minor asks for the next minor version rather than the next patch.
• --by says who's asking.
• --json prints the claim as JSON, for scripts.

Set exactly the version it hands out, in the files it names, and in the changelog: other work started beside yours has claimed the ones around it.

How the version is chosen#

It's the next version no one has. That's above all of these:

• the version on the repository's branch on GitHub;
• every release;
• every open pull request's version, read from its title;
• every live claim.

Claims are handed out one at a time, so two pieces of work asking at once get two versions. Put the version in your pull request's title (Example App 1.4.3: search in the toolbar), as that's where the Steward reads it.

How long a claim lasts#

A claim lives until:

• its version is on the branch, or a release has overtaken it (the work landed);
• you give it back;
• three days go by with no open pull request that names it (by its branch, or its version in the title).

Each round lets go of the ones that ended. While a claim lives, another pull request that sets that version is held, and caught up to a free one.

Give one back when the work is dropped:

node $HOME\.steward\app\src\cli.ts release-version example-app 1.4.3

List them with claims (or claims --json).

Across your PCs#

Claims are shared by every PC that looks after the repository, through a ref in the repository's own remote (refs/manor/claims), with plain git. When the remote can't be reached, the claim is made on this PC alone, and shared at the next round that reaches it. If another PC claimed the same version meanwhile, the page marks it, and that work gets a new version when it merges. See The Steward on several PCs.

Changelog entries in a changes folder#

Pull requests side by side still meet in the same lines: the version files, and the top of CHANGELOG.md. A repository can avoid that altogether.

Add a changes/README.md to the repository's branch (it can say anything: what the folder is for). From then on:

1. claim-version says to write the entry in changes/<version>.md, and to leave the version files and CHANGELOG.md as they are.
2. The work adds that one file: the entry for its version (its bold line, then its sections), without the ## <version> heading.
3. Just before merging, the Steward stamps the pull request: it merges the repository's branch into it, sets the version in the version files, folds the entry into CHANGELOG.md under ## <version>, and deletes the file, all in one commit pushed to the pull request's branch.
4. Then it merges it.

If the version was released or taken meanwhile, the pull request gets the next free one (a minor step stays minor), and its title and claim follow. An empty entry, or one whose heading names another version, waits for whoever wrote it. A stamped pull request always merges on its own, never stacked with others.

A release then carries the entries of every version merged since the release before, so one release after several merges loses no notes.