Release

Releasing geoparquet-io

Every release section of CHANGELOG.md is generated, never hand-written. It is GitHub's own release-note list — one line per pull request, with its author and number — grouped into Keep a Changelog sections, under two to four paragraphs of highlights that you write.

There is a mandatory human review checkpoint at step 5. Nothing is bumped, tagged or published before the user approves the changelog section.

1. Preflight

git checkout main && git pull
gh run list --branch main --limit 5          # main must be green
git status --short                            # must be clean
uv run pytest -n auto -m "not slow and not network and not meta"

Pick the version from what merged: a ! title or a withdrawn command means minor at least (this project is 1.x and pre-1.0 rules no longer apply), new commands mean minor, fixes alone mean patch.

2. Generate the section

uv run python scripts/release_notes.py <version> --previous v<previous> --write

This replaces the ## Unreleased block with the new section. It refuses to run twice for one version. Without --write it prints to stdout, which is the way to preview.

3. Retitle whatever landed in ### Uncategorized

Pull requests whose titles carry no conventional-commit type land there. Do not edit the changelog by hand and do not touch the pull request: add a rewritten title to scripts/release_title_overrides.json, keyed by PR number, and run the generator again. The type you give it is what files the entry.

"645": "fix(geometry): stop the SIGSEGV in repair on tables with NULL geometry rows"

Read each pull request before you retitle it, and write the line a user should read. A test, ci, chore, style or build type files the entry as housekeeping, which is not listed — correct for a chore, wrong for a fix wearing the wrong type, so pick deliberately. Two judgements the script cannot make:

• Give it a ! when the change removes a command, changes a default, or withdraws a capability, even though the merged title had none. Squash merges take the PR title, so a ! written in a commit body is already lost. This is how an entry reaches ### Breaking.
• Human dependency decisions — a pin relaxed, a floor raised for a CVE — take build(deps) so they sit with the bot bumps.

Regenerate until ### Uncategorized is gone. Rerunning is safe: the overrides file makes the whole section reproducible, so nothing is lost to a second run.

4. Write the highlights

Replace the <!-- TODO ... --> placeholder with two to four paragraphs, written after reading the Breaking, Added and Changed entries. Cover, in this order:

1. What is newly possible — the commands and capabilities added.
2. The theme of the fixes, named concretely, not "various bug fixes".
3. Every breaking change, with what a user has to do about it.
4. Every first-time contributor, by name, with what they contributed.

The last paragraph is not optional. Get the material from:

uv run python scripts/release_notes.py <version> --previous v<previous> --contributors

That prints every pull request each new contributor wrote, not only the first one GitHub names. For each person: say how many pull requests they sent when it was more than one, summarize the work in a sentence or two — the actual substance of it, so they can see they were read — thank them, and close by inviting them back. Do not reduce a run of ten pull requests to "various fixes".

Do not restate the entry list. Aim for what a user needs to decide whether to upgrade, and what a contributor needs to feel their work was noticed.

5. Human review — STOP HERE

Show the user the rendered section and wait for explicit approval. Say what you want checked:

• the version number
• the summary paragraphs
• any entry you moved out of ### Uncategorized, and anything you promoted to ### Breaking

Do not run step 6 until the user approves. If the release ships alongside other work, put the changelog in that pull request and let review happen there.