This document outlines the conventions for working in this repository. They keep the project consistent and maintainable as it grows across people and AI agents.
Commit messages follow the Conventional Commits specification, which keeps the project history readable and easy to scan.
Each commit message consists of a mandatory type, scope, and description, optionally followed by a body and a trailer:
<type>(<scope>): <description>
[body]
[trailer]
The first line must be lowercase, and must not exceed 100 characters.
Must be one of the following:
- build: Changes that affect the build system or external dependencies
- chore: Maintenance tasks
- docs: Documentation only changes
- feat: A new feature
- fix: A bug fix
- perf: A code change that improves performance
- refactor: A code change that neither fixes a bug nor adds a feature
- style: Changes that do not affect the meaning of the code
- test: Adding missing tests or correcting existing tests
The scope is the name of the package affected, as perceived by someone reading the changelog generated from commit messages. Use common for repository level changes that are not tied to a single package, such as CONTRIBUTING.md or README.md.
The description is a brief summary of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- the entire first line (type, scope, and description) must be lowercase
- no dot (.) at the end
A body describes what the commit introduces or changes. It may span any number of paragraphs separated by blank lines. Do not hyphenate and break words in body text.
If a commit was made with AI assistance, add a Assisted-by trailer:
Assisted-by: <agent-name>/<model-id>
Pass --trailer directly on the commit command. This is the clean path and avoids amend noise:
git commit -m "feat(scope): add support for x..." --trailer "Assisted-by: <agent-name>/<model-id>"If the commit reverts a previous commit, it should begin with revert:, followed by the description of the reverted commit.