Day-to-day PR workflow
From opening an issue to publishing a release.
1. Open an issue (optional)
Three issue templates are available:
| Template | Use when | Issue Type |
|---|---|---|
| Bug Report | Reproducible bug with clear expected vs actual behaviour | Bug (set automatically) |
| Feature Request | New functionality or enhancement proposal | Feature (set automatically) |
| Something is not working | Unexpected behaviour where root cause is unclear | (none set) |
The issue Type is set automatically by the Bug Report and Feature Request templates.
Issue Type vs PR label
These are separate. The issue Type categorises the issue for the project board. The PR label (step 3) is what drives the changelog and version bump. It must still be applied manually on the PR (see below).
2. Open a pull request
Branch off main using the PR branch name guide below, make your changes, publish branch and start the PR.
| Type | PR Title | PR branch name |
|---|---|---|
| With linked issue | Fix memory leakage |
42-fix-memory-leakage |
| Without an issue | Add support for custom node weights |
add-support-custom-node-weights |
Info
Do not include the issue number in the PR title. The changelog template already appends the PR number automatically ((#15) style). Putting both produces two different numbers in one line.
The title is written for someone reading the changelog months later, not for the diff reviewer. Keep it concise and factual.
Opening description
This is only for reviewers. It does not appear in the changelog. Use it to explain context, trade-offs, or anything a reviewer needs to know.
Linking issues
Add Fixes #42 or Closes #42 in the PR description. GitHub auto-closes the linked issue when the PR merges.
Style Guide
If the issues are enumerate (e.g. - Fixes #42), the title of the issue is being displayed instead of just the number.
What ends up in the changelog
| What you write | Changelog field | When |
|---|---|---|
| PR title | $TITLE: The heading line for this entry |
When the PR is opened; confirmed at merge |
3. Apply exactly one bump label
See the full label reference for colours, bump types, and version resolution rules.
| Label | Use when | Version bump |
|---|---|---|
| breaking | Removes or alters existing behaviour in a way that breaks callers | MAJOR x+1.y.z |
| feature | New functionality that is backwards-compatible | MINOR x.y+1.z |
| fix | Bug fix | PATCH x.y.z+1 |
| dependencies | Dependency version bump | PATCH x.y.z+1 |
| chore | CI changes, refactoring, test additions, or any work that does not affect the public API. Bypasses the gate; excluded from changelog; no version bump. | none |
The label-gate / check status check blocks merge until exactly one label is present. It re-runs automatically when you add or remove a label, so you can fix a missing label without pushing new commits.
4. Review and approval
Normal PR review. Branch protection on main requires (usually) at least one approval. This process may be different amongst repositories.
5. Squash-merge
Confirm the PR title is accurate before clicking merge - it is the only field that appears in the changelog. The extended description box is not read by the release system; leave it blank.
6. Automatic draft update
After merge, release-drafter appends this PR's entry to the standing draft release and recomputes the suggested next version from the highest-priority bump label seen across all included PRs.
Repeat steps 2-6 for each PR. The draft accumulates entries until a release is published.
7. Publish the release
When ready to ship, go to the Releases page, open the draft, review or edit the body if needed, and click Publish release.
Publishing creates a git tag on current main HEAD. The tag push triggers publish.yml, which builds the wheel and uploads to PyPI. The version in the wheel is derived from the tag by hatch-vcs; no file in the repository is modified.
8. Verify
Check the Actions tab for the Publish workflow run. Confirm the upload succeeded and the new version appears on PyPI.