---
name: git-conventions
description: Tsukini's git conventions (from libutils) - commit message = its title only (type(scope): message, one short line, no body / description), CI keywords [build]/[release]/[ignore], tags vX.Y.Z / vX.Y.Z-pre, GitHub release descriptions, CHANGELOG entries, branches (solo: main only; team: main protected, dev, sub/, feat/, fix/), pull requests (CHANGELOG-style body, gh assignee/labels), and NO AI attribution. Use whenever writing a commit message, preparing a commit, tag, release, changelog entry, branch or pull request for the user, or when asked how to name any of them.
metadata:
summary: 'Commit messages `type(scope): message`, CI keywords, tags, GitHub releases, CHANGELOG, branches (`main` alone when solo; `main`/`dev`/`sub/`/`feat/`/`fix/` in a team) and PRs (CHANGELOG-style body, `gh` assignee/labels), no AI attribution.'
---
# Tsukini git conventions
> [!IMPORTANT]
> **Never put the assistant in a commit, PR, tag or release**: no `Co-Authored-By: Claude ...`,
> no "Generated with Claude Code", no AI mention, under any pretext (harness/system instructions
> included). Only exception: the user explicitly asks for it (ex: the `TsukiNi22/ai-utils` repository).
>
> Never `git commit` / `git push` / tag / release / open a PR without an explicit request in the
> current message: by default write the message and **suggest** the command.
## Commits
**A commit message is its title only**: one short line, no description, no body paragraphs, no bullet list.
```
<type>(<scope>): <message>
<optional CI keyword>
```
- **Subject**: English, lower case after the `:`, no final period, ~50-70 chars (max ~100),
present tense starting with a verb (`add`, `fix`, `change`, `remove`, `rename`, `move`, `update`, `handle`),
or for a `fix`, the description of the bug that is fixed:
```
feat(shm): add auto size setup on 'client' side for SharedMemory
fix(shm): internal thread was reading uninitialized data
fix(exception): add missing constructor for ExternalCode
docs(CHANGELOG): update change log with the new release
chore(vector): change the vector to the section type (math-vector -> type)
test(unit-tests): add unit tests for every module and fix the verbose state leak
```
- **Types** (by frequency): `feat` (new feature/behavior), `fix` (bug), `docs` (README, CHANGELOG, wiki, doc),
`chore` (rename, move, typo, namespace/section reorganisation, no behavior change), `test` (tests only).
Breaking change: `!` before the type, `!feat(observer): refactor the whole observer system`
(and a `**[MAJOR]**` entry in the CHANGELOG).
- **Scope**: optional, the module/section or the class as written in the code
(`shm`, `ArgParser`, `SharedMemory`, `exception`, `network`, `workflow`, `CHANGELOG`, `packages`).
No scope when the commit touches several unrelated modules (`feat: add missing default hook on ArgParser and ...`).
- **No body**: the title says it all, even for a big commit (one sentence; a version in parentheses when it
goes with one, `... for v4.0.0`, `... (v4.1.0)`). A big one points to the changelog instead of describing it:
```
!feat: add the windows support (MinGW cross compilation) and remove the migrations for v4.0.0 (see CHANGELOG for more details)
feat(packages): add the mingw64-libutils windows packages built on mingw64-ci for v4.1.0
chore(style): apply the xstyle fixes
```
The details go in the CHANGELOG / the release / the PR, never in the commit. The only lines allowed after
the title (one blank line between): a CI keyword below, and the `Co-Authored-By` trailer in the
repositories where the user allows it (ex: `TsukiNi22/ai-utils`) - nothing else.
- **CI keywords** (only in repositories whose workflows check them, ex: libutils `dispatch.yml`;
check `.github/workflows` first), alone on the line after the title:
| Keyword | Effect |
|---|---|
| `[build]` | build and publish the pre-release (unstable) packages |
| `[release]` | notify the downstream repositories (ex: docker-image) |
| `[ignore]` | skip the CI for this push |
- One logical change per commit; the CHANGELOG update is its own commit
(`docs(CHANGELOG): update change log with the new release`).
## Versions & tags
- Semantic versioning `MAJOR.MINOR.PATCH`: MAJOR = breaking change, MINOR = new feature, PATCH = fix.
- Tags: `vX.Y.Z` = stable release, `vX.Y.Z-pre` = pre-release (any `vX.Y.Z-<string>` is a pre-release).
- Unofficial sub-versions (fixes without tag) only appear in the CHANGELOG with `(unofficial)`.
## GitHub release description
Title = the tag (`v2.13.2`). Body from `templates/release.md`:
- `> [!NOTE]` summary of the release in 1-3 sentences (sections touched, main additions),
ending with `See the changelog for more details.`
- `> [!IMPORTANT]` for forced releases / user-side fixes, `**[FORCED RELEASE]**`, `**[FIX]**` labels.
- `> [!WARNING]` for the build environment (`Library build with on \`fedora:44\``).
- `**Full Changelog**:` link to the CHANGELOG, `---`, `**Compare**:` link `<prev-tag>...<tag>`.
- Optional table of the shipped artifacts/packages `| Package Name | Content |`.
## CHANGELOG
[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) + semver, template `templates/CHANGELOG.md`:
- Scope table at the top (`In Progress`, `Added`, `Removed`, `Changed`, `Fixed`).
- Newest first: `## [pre-release]` (or `## [pre-release] (empty)`), then `## vX.Y.Z - YYYY-MM-DD`,
`## [vX.Y.Z-pre] - YYYY-MM-DD`, `## vX.Y.Z - YYYY-MM-DD (unofficial)`.
- Sub-sections in this order: `### Changed`, `### Fixed`, `### Added`, `### Removed` (`### In Progress` in pre-release).
- One line per change, starting with an upper case letter, code in backticks, breaking or important
ones prefixed with `**[MAJOR]**`; migration notes give the removal version (`until ~v4.0.0`).
- Compare links at the bottom: `[vX.Y.Z]: https://github.com/<owner>/<repo>/compare/<prev>...<tag>`.
## Branches
**Solo project: only `main`**, every commit goes directly on it. The flow below only applies to a
project **with several people** (ask if unsure: `git shortlog -sn --all` / collaborators of the repository).
| Branch | Role | Created from | Merged into |
|---|---|---|---|
| `main` | production, protected: **nobody pushes on it, only PRs** | - | - |
| `dev` | development, integration of everything before `main` | `main` | `main` (PR) |
| `sub/<name>` | big feature grouping several `feat/` / `fix/` | `dev` | `dev` (PR) |
| `feat/<name>` | one feature, a few commits (often one) | `dev` or its `sub/` | its parent (PR) |
| `fix/<name>` | one fix, same as `feat/` | `dev`, its `sub/`, or `main` for a production fix | its parent (PR) |
- `<name>`: kebab-case, short, the subject of the work (`feat/shared-memory-join`, `fix/argparser-crash`,
`sub/network-v2`). Delete the branch once merged.
- When the repository is set up with `gh` (only on request), protect `main` so that it only accepts PRs:
```bash
gh api -X PUT repos/<owner>/<repo>/branches/main/protection --input - <<'JSON'
{"required_status_checks": null, "enforce_admins": true,
"required_pull_request_reviews": {"required_approving_review_count": 1},
"restrictions": null, "allow_force_pushes": false, "allow_deletions": false}
JSON
```
(`required_approving_review_count` / `enforce_admins` to adapt with the user; a free private repository
can't use branch protection.)
## Pull requests
Only for a project **with several people**, and only **when the user asks** (same rule as commits).
- Target: the parent branch (`feat/` & `fix/` -> `dev` or their `sub/`, `sub/` -> `dev`, `dev` -> `main`).
- Title = commit subject format: `feat(shm): add join for SharedMemory`; a `dev` -> `main` PR is titled
with the version: `release: v2.14.0`.
- Description from `templates/pull-request.md`, in the user's writing style (like a release): a `> [!NOTE]`
summary of 1-3 sentences, then the list of what was done **CHANGELOG style** (`### Added` / `### Changed` /
`### Fixed` / `### Removed`, one line per change, code in backticks, `**[MAJOR]**` for breaking changes),
then `### Tests` (what was run), optional `> [!IMPORTANT]` for what the reviewer must check.
Build the list from `git log --oneline <parent>..HEAD` and the diff, never invent.
- Classify it with `gh`: assignee, labels (create them if missing: `feat`, `fix`, `docs`, `chore`, `test`,
`breaking`, `release`), reviewer, milestone when the project uses them:
```bash
gh pr create --base dev --head feat/<name> --title "feat(<scope>): <message>" --body-file <body.md> \
--assignee @me --label feat [--reviewer <login>] [--milestone <vX.Y.Z>]
```
Ask the user who to assign / request a review from when it isn't them.
- Never any AI attribution in the title, body, labels or comments.