Vouching, and pull requests the Steward opens

Why vouch#

When GitHub runs no checks on a pull request, the Steward runs the repository's tests on this PC before it merges it. If you've just run them yourself, that's the same work twice. Vouching says you did: the Steward then merges the pull request without testing it again.

Vouch for a pull request#

In the clone you pushed from, with the pull request's head checked out and nothing uncommitted:

node $HOME\.steward\app\src\cli.ts vouch

Or vouch 134, to name the pull request rather than the one for this branch. It:

1. Runs the repository's tests, as its Tests say, at your clone's HEAD (only what the change reaches, while Tests only what a change reaches is on).
2. When they pass, sets a commit status on that commit on GitHub: steward/tested, success. A failure sets none.
3. Asks the Steward for a round now, so the pull request merges in minutes rather than at the next round.

The Steward then merges it without testing it here: "merged #17 (checks passed at abc1234 in octocat's clone, vouched for)".

When a vouch counts#

Only while all of these hold:

• the latest steward/tested status on the pull request's current head says success;
• one of your team's accounts set it (GitHub records who did);
• the pull request comes from the repository itself, not a fork.

Push again after vouching and the new commit is tested here as before, unless you vouch again. A catch-up keeps the vouch only where it resolved nothing but version lines and changelogs. The status isn't a check GitHub runs, so it never makes a pull request's checks "passing" on its own.

When vouch refuses#

It says why, in a sentence:

• It has uncommitted changes: commit and push them first. It vouches only for a commit as pushed.
• The pull request's head isn't this clone's HEAD: push, or check out its head, and vouch again.
• No open pull request for this branch: push, open one, or let the Steward open it (below).
• It's from a fork: the Steward tests those itself.
• The repository isn't one the Steward looks after: it has no tests to run. See Choosing what the Steward looks after.

Let the Steward open the pull request#

Your work needn't open its own pull request. Claim a version for the branch, push it, and vouch with no pull request open:

1. claim-version example-app --branch feature/search --for "search in the toolbar", and set that version. See Versions claimed up front.
2. Commit, and push the branch.
3. vouch, in the clone.

The tests run, the vouch is set on the pushed commit, and the Steward is asked for a round. At that round it opens a ready pull request for the branch:

• Its title: "<Name> <version>: " and the first bold line of the version's changelog entry.
• Its description: the entry, then who vouched for which commit, and what the claim says the work is.

The same round then merges it as any vouched pull request, where merging is allowed. It's opened only when the branch is on GitHub at the vouched commit, has no open pull request, isn't merged already, and wasn't closed at that same head.

Tell your assistant#

Give your AI coding assistant the steps in its instructions file, so it claims, pushes and vouches on its own. For example:

Before work that raises a repository's version, claim the version from the Steward once you know your branch:
node %USERPROFILE%\.steward\app\src\cli.ts claim-version <repo> --branch <branch> --for "<what the work is>"
Set exactly the version it hands out, in the files it names and in CHANGELOG.md.

Once the branch is pushed, vouch for it from its clone, with nothing uncommitted:
node %USERPROFILE%\.steward\app\src\cli.ts vouch
Vouch again after every push. If it fails, fix what failed.