mainis the release branch;devis the integration branch.- Branch off
devand open your PR againstdev.devreachesmainonly through a release PR, merged with a merge commit (never squashed), so the two branches never diverge. - CI must be green to merge: tests, lint, and the news-fragment check.
- Enable the local pre-commit hook once per clone:
git config core.hooksPath .githooks.
Release notes are built from small "news fragment" files,
not from commit messages,
so they are written for end users and survive any merge strategy.
Every PR into dev must add at least one fragment.
CI enforces this;
the only exception is a release-batch PR,
which consumes fragments instead of adding them.
A fragment is one file with one user-facing sentence:
.changes/<pr>.<type>.md
Create it with the helper (flags for scripts and agents, prompts for humans):
# non-interactive
go run ./tools/changelog new -pr 17 -type enh "\`wt new\` refuses to reuse a checked-out branch."
# interactive: prompts for PR number, type, and message
go run ./tools/changelog newOr write the file by hand; the tool only saves typing. Describe the change to end users, one sentence, ending with the PR reference the tool appends for you:
$ cat .changes/17.enh.md
`wt new` refuses to reuse a checked-out branch. (#17)
| Type | Changelog heading | Use for |
|---|---|---|
enh |
Enhancements | New commands, flags, and behavior improvements |
bug |
Fixes | Anything a user could have hit |
dep |
Deprecations | Commands, flags, or config keys scheduled for removal |
doc |
Documentation | User-facing docs (not code comments) |
maint |
Infrastructure | CI, build, release, and tooling changes users never see |
go run ./tools/changelog pending-
Branch off
dev, batch the staged fragments, and PR back intodev(the fragment check passes because fragments are consumed):go run ./tools/changelog batch v0.1.0-alpha.2 git add -A && git commit -m "chore: collect release notes for v0.1.0-alpha.2"
-
PR
devintomainand merge with a merge commit. -
Tag
mainwith the batched version and push the tag:git tag v0.1.0-alpha.2 && git push origin v0.1.0-alpha.2The release workflow extracts this version's section from
CHANGELOG.mdand publishes it as the GitHub release notes; tagging a version that was never batched fails the release job.