Git Commit Message Rules¶

All commits in this repository must follow the Conventional Commits specification. This is enforced because git-cliff parses commit messages to automatically generate changelogs and release notes.

Format¶

<type>(<scope>): <short summary>
                  │
                  └─ Written in imperative mood. No period at the end.
                     Example: "add user login endpoint" not "added user login endpoint"

<optional body>
                  │
                  └─ Explain *what* and *why*, not *how*. Wrap at 72 characters.

<optional footer(s)>
                  │
                  └─ BREAKING CHANGE: <description>
                     Refs: #<issue-number>

Rules¶

The first line must not exceed 72 characters.
Type is required. Must be one of the types listed below.
Scope is required. Must be one of the scopes listed below.
Summary is required. Written in imperative present tense ("add" not "added" or "adds").
Body is optional. Use it to explain motivation and context when the summary alone isn't enough.
Footer is optional. Used for breaking changes and issue references.

Types¶

Type	Description	Appears in Changelog
`feat`	A new feature	Yes — Features
`fix`	A bug fix	Yes — Bug Fixes
`perf`	A performance improvement	Yes — Performance
`refactor`	Code change that neither fixes a bug nor adds a feature	Yes — Refactoring
`docs`	Documentation only changes	Yes — Documentation
`style`	Formatting, whitespace, semicolons (not CSS changes)	Yes — Styling
`test`	Adding or correcting tests	Yes — Testing
`build`	Changes to the build system or external dependencies	Yes — Build
`ci`	Changes to CI/CD configuration and scripts	Yes — CI/CD
`chore`	Maintenance tasks that don't modify src or test files	Yes — Miscellaneous
`revert`	Reverts a previous commit	Yes — Reverted

Scopes¶

Scope	When to use
`server`	Rust backend code
`android`	Android app
`ios`	iOS app
`docs`	Documentation site
`infra`	Infrastructure, CI/CD, deployment
`erp`	ERP domain logic (can combine: `server/erp` is also acceptable)
`hris`	HRIS domain logic
`crm`	CRM domain logic
`auth`	Authentication and authorization
`api`	Internal or Open API surface
`db`	Database schema, migrations

Breaking Changes¶

When a commit introduces a breaking change:

Append ! after the type/scope
Include a BREAKING CHANGE: footer explaining what breaks and how to migrate

feat(api)!: change authentication endpoint response format

The /api/v1/auth/login response now returns tokens in a nested
"tokens" object instead of at the top level.

BREAKING CHANGE: Clients must update their token parsing to read
from response.tokens.access_token instead of response.access_token.
Affects both mobile apps and any external integrations.

Examples¶

Simple feature¶

feat(auth): add refresh token rotation endpoint

Bug fix with context¶

fix(server): prevent panic on empty request body

The JSON deserializer was called before checking Content-Length,
causing a panic on requests with no body. Now returns 400 Bad Request.

Refs: #42

Documentation¶

docs(crm): add lead pipeline flowchart

CI change¶

ci(infra): add cargo clippy step to server workflow

Refactoring¶

refactor(erp): extract invoice calculation to domain service

Moves tax and discount calculations out of the handler and into
a pure domain service, improving testability.

Multiple scopes (use the most specific one)¶

feat(hris): add employee leave balance calculation

Revert¶

revert: feat(auth): add refresh token rotation endpoint

This reverts commit abc1234. The rotation logic caused token
invalidation issues in production.

What Happens If You Don't Follow These Rules¶

git-cliff will skip non-conforming commits when generating changelogs — your changes won't appear in release notes.
CI may be configured to reject non-conforming commit messages in the future.

Tips¶

Write the summary as if completing the sentence: "If applied, this commit will _____"
Keep the summary concise. Put details in the body.
Reference issue numbers in the footer, not the summary.
One logical change per commit. Don't mix a feature and a refactor in the same commit.