---
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

```sh
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

```sh
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:

```sh
hg update <bookmark-name>
```

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

```sh
hg bookmark <feature-name> -r .
```

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

### 3. Verify history is clean

```sh
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:

```sh
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

```sh
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:

```sh
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.