Git conventions and the changelog
The big picture: Every change follows the same shape: a prefixed branch, conventional commit messages, a merge request, and a one-line changelog fragment.
Why it matters: When every change looks the same, both people and agents can read history at a glance — and release notes write themselves from the fragments instead of from memory the night before.
The rules in one breath:
- Branch:
feat/,fix/,docs/,chore/, … plus the issue number and a slug. - Commit:
type(scope): what changed— e.g.fix(api): prevent N+1 on project list. - Never commit to
main; every change goes through an MR, even docs and chores. - Add
changelog.d/<issue>.<type>.mdwith one user-facing line.
Branch naming
Section titled “Branch naming”All branches use a prefix that maps to conventional commit types:
feat/ — new featuresfix/ — bug fixesdocs/ — documentation onlychore/ — maintenance, config, CItest/ — test-only changesrefactor/— restructuring without behavior changeperf/ — performance improvementsci/ — CI pipeline changesExample: feat/user-onboarding, fix/login-race-condition
Commit format
Section titled “Commit format”Conventional commits with an optional scope:
feat(auth): add OAuth2 PKCE flowfix(api): prevent N+1 on project list endpointdocs: update deployment guide for Helm 3.14chore(ci): pin runner image to node:20-alpineMerge request workflow
Section titled “Merge request workflow”Every change goes through a branch and an MR, including docs, chores, and hotfixes:
- Start from an issue:
scripts/wt new <issue>creates the branch and a worktree off the latest default branch. For a single change on a clean checkout,git checkout main && git pull origin main && git checkout -b <prefix>/<issue>-<slug>works too. - Make changes, commit, and push the branch
- Run
/mrto open the MR with pre-flight checks - Wait for a green pipeline, then merge
- From the main checkout, run
scripts/wt pruneto remove the merged worktree
/mr writes a structured description (summary, changes, test plan, gate results, and
Closes #N). It also checks that a changelog fragment exists unless the branch is
exempt.
Changelog system
Section titled “Changelog system”The template uses fragment-based changelogs instead of direct CHANGELOG.md edits.
This eliminates merge conflicts and enforces that every MR documents its changes.
How it works
Section titled “How it works”-
During development: Write a file in
changelog.d/(thechangelogagent can draft it):changelog.d/├── 42.added.md # "Add user onboarding flow"├── 57.fixed.md # "Fix login race condition on slow networks"└── oauth-pkce.added.md # "Add OAuth2 PKCE authentication" -
CI enforcement: The
changelog-checkjob fails an MR that changes product files without adding a fragment, and fails ifCHANGELOG.mdis edited directly outside achore/release-<version>branch. It also fails (rather than skips) when it cannot compute the diff. Add theno-changeloglabel to exempt a specific MR from the fragment rule. Locally,make check-changelogruns the same script (CI_MERGE_REQUEST_LABELS=no-changelog make check-changelogmimics the label). -
At release time:
scripts/assemble-changelog.shcollects all fragments, groups them by type (Added, Changed, Fixed, Security), inserts them intoCHANGELOG.mdunder the new version heading, and deletes the consumed fragment files.
Fragment naming
Section titled “Fragment naming”<issue-number-or-slug>.<type>.md- Types:
added,changed,fixed,security - Content: One line describing the change from the user’s perspective
- When CI skips the check: the branch starts with
chore/, or every changed file is non-product (CI config,docs/,scripts/,README*,CLAUDE.md,AGENTS.md,changelog.d/,Makefile,.gitignore, or any*.md/*.shfile; other files under.claude/, such assettings.json, need a fragment), or the MR has theno-changeloglabel. A dependency bump that changes a lockfile is not skipped unless it is on achore/branch. Add test directories to the filter list inscripts/check-changelog.sh(see theAdd your test directories herecomment) if test-only changes should skip too.
Lockfile conflicts: regenerate, never union-merge. package-lock.json, yarn.lock
and pnpm-lock.yaml have no merge=union rule in .gitattributes, because a union
merge concatenates both sides into duplicated or inconsistent entries that still parse.
On a conflict, take either side, run npm install (or yarn install / pnpm install),
and commit the regenerated file.