---

name: mercurial-finishing-a-branch
description: Use when an implementation is complete and ready to be proposed as a pull request — runs the pre-PR checklist (build, vet, format, test) and walks through pushing the bookmark and opening a PR. The Mercurial counterpart to superpowers' finishing-a-development-branch.

Mercurial: finishing a development branch

When this applies

Use when:

• Implementation is complete and the user is ready to propose a PR.
• The user says "let's ship this" / "this is done" / "let's open a PR" in an hg repo.

Do not use for:

• Mid-development commits → see mercurial-basics.
• Recovering from a bad commit → see mercurial-history-rewriting.

The flow

Six steps. Do them in order; do not skip.

1. Verify the working directory is clean

hg status

Expected: empty output. If anything is shown:

• New files you intended to include → hg add and amend the tip commit.
• New files you didn't mean to track → add to .hgignore and commit that change separately.
• Modified files → either amend or commit them as a separate change.

Do not push with uncommitted changes lingering.

2. Verify you're on the right bookmark

hg bookmarks

The active bookmark is marked with *. Confirm it's the feature bookmark, not e.g. an accidental commit on no bookmark.

If a feature bookmark exists but isn't active:

hg update <bookmark-name>

If commits were made without an active bookmark (anonymous head):

hg bookmark <feature-name> -r .

(See mercurial-bookmarks-and-prs for the bookmark mechanics.)

3. Verify history is clean

hg log -l 10 --template '{node|short} {phase} {desc|firstline}\n'

Look for:

• All commits should be draft (in non-publishing repos like Isurus).
• Commit messages follow the convention (imperative summary, <72 chars, "category: summary" prefix where the project uses one).
• No "wip", "fix typo", "address review" debris — squash via hg amend / hg uncommit.

If cleanup is needed → see mercurial-history-rewriting. The non-publishing repo means amend is safe even on already-pushed changesets.

4. Run the project's pre-PR checks

Detect the project's check command:

ls Makefile 2>/dev/null && grep -E '^(check|test|fmt|vet|lint):' Makefile

Common patterns:

• Has Makefile with check target: make check (full test suite). Then run make fmt and make vet if those exist.
• Go project, no Makefile: go test ./..., go vet ./..., gofmt -l . (anything output = unformatted).
• Other languages: match the project's documented test/lint commands.

For the Isurus repository specifically, see isurus-conventions — it documents the exact make targets used.

If checks fail, fix or surface before continuing. Do not push code that fails the project's own gate.

5. Push the bookmark

hg push -B <bookmark-name>

The -B <bookmark-name> is critical — without it the changesets push but the remote doesn't know to associate them with a bookmark/PR.

If the push is rejected because the bookmark was previously pushed and has since been amended:

hg push -B <bookmark-name> -f

-f is the expected workflow in non-publishing repos after hg amend. See mercurial-bookmarks-and-prs for context.

6. Open the pull request

In the forge web UI:

1. Navigate to the repository.
2. The forge typically shows a banner offering to open a PR for the just-pushed bookmark — click it.
3. Title the PR using the same format as the commit message summary.
4. PR description: explain why, link any related issues. The diff shows what; don't repeat it in the description.

For Isurus-specific URL patterns and PR conventions → see isurus-conventions.

After the PR is open

When reviewer feedback comes in:

• Make the requested changes locally.
• hg amend to fold the fix into the existing changeset (in non-publishing repos).
• hg push -B <bookmark-name> -f.
• Reply to the review comments confirming the fix is pushed.

When the PR is merged:

• hg pull -u to bring the merged changes locally.
• hg bookmark -d <bookmark-name> to delete the local bookmark.
• Optionally hg push --delete <bookmark-name> if the forge doesn't auto-delete on merge.