You will learn#
- the format of a commit header, and the types and scopes that are accepted;
- how a commit becomes an entry of the release notes;
- what a pull request must show before it is merged.
The idea#
Commits follow Conventional Commits 1.0 in English. A pull request is rebase-merged, so every commit of the branch reaches main as it is and is what the changelog reads. That is why each commit is small, self-contained and written for a reader of the release notes. One logical change goes in one commit and one pull request.
<type>(<scope>)!: <description>
[body]
[footer(s)]- Types:
feat,fix,perf,refactor,docs,test,build,ci,chore,style,revert. - Description: imperative, starts with a lower-case letter, has no final period, and the whole header is at most 100 characters.
- Scope: optional; one of
core,timeline,schema,command,plan,lint,engine,raster,ingest,export,image,transcribe,installers,service,workspace,web,api,mcp,cli,ui,site,docs,repo,ci,deps,deps-dev,release,adr,sdd,goorsecurity. - Footers:
BREAKING CHANGE:describes the impact of a breaking change (also mark it with!);Security:gives one line on the risk a security fix closes;Refs: P1-ENG-003orFixes #123names the task or issue.
Quick start#
- Write the commit with a type that fits the notes. Release notes have five sections:
featgoes to Added, a breaking commit to Changed,revertor aRemoved:footer to Removed,fixto Fixed, and aSecurity:footer or the scopesecurityto Security. Other types are left out. - Run the checks before you push:
task ci, andtask site:buildwhen you changedsite/. - Open the pull request with the template filled in: the task or issue, the checks you ran, the thin-client rule and any friction with the framework.
- Fold fixup commits before you ask for the merge. A pull request that fixes a bug has the test in the same commit as the fix.
A commit that changes only the wording of an English page and needs no new translation carries a line Translation: not-needed in its message; see Translating the documentation.
Common mistakes#
- A header over 100 characters, a capital letter after the colon, a final period or a scope that is not in the list: the commit check fails and the header must be rewritten.
- Marking a change
featwhen it fixes a bug: it ends up in Added instead of Fixed. - Editing
CHANGELOG.mdby hand. It is generated from the commits when a release is prepared. - Pushing to
mainor force pushing a shared branch.mainis protected: a change reaches it only through a pull request with green checks, and the maintainer does the merging. - Putting a task id in the header instead of the body.