Based on the Conventional Commits v1.0.0 specification.
The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are interpreted as described in RFC 2119:
- MUST / REQUIRED / SHALL — absolute requirement
- MUST NOT / SHALL NOT — absolute prohibition
- SHOULD / RECOMMENDED — may be ignored with good reason, but implications must be understood
- SHOULD NOT / NOT RECOMMENDED — may be acceptable with good reason, but implications must be understood
- MAY / OPTIONAL — truly optional
Commit Message Format
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Prefer the shortest form that fully conveys the change. Most commits SHOULD be a single line (`type[scope]: description`). Only add body or footers when the description alone cannot convey enough context.
## Types
`feat` MUST be used for new features (correlates with SemVer MINOR). `fix` MUST be used for bug fixes (correlates with SemVer PATCH). Other types MAY be used. The following are RECOMMENDED (based on the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type)):
| Type | Purpose |
|------|---------|
| `feat` | New feature |
| `fix` | Bug fix |
| `build` | Build system or external dependency changes |
| `chore` | Maintenance tasks, no production code change |
| `ci` | CI configuration and scripts |
| `docs` | Documentation only |
| `style` | Formatting, whitespace — no logic change |
| `refactor` | Code restructuring — no feature or fix |
| `perf` | Performance improvement |
| `test` | Adding or updating tests |
## Rules
### Structure
1. Commits MUST be prefixed with a type (a lowercase noun), followed by an OPTIONAL scope, an OPTIONAL `!`, and a REQUIRED terminal colon and space (`: `)
2. A scope MAY be provided after the type. A scope MUST be a noun in parentheses describing a section of the codebase: `fix(parser): ...`
3. A description MUST immediately follow the `: ` after the type/scope prefix
4. A body MAY be provided after the description. It MUST begin one blank line after the description, is free-form, and MAY consist of any number of newline-separated paragraphs
5. One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token followed by `:<space>` or `<space>#` separator, followed by a string value. Footer tokens MUST use `-` in place of whitespace (exception: `BREAKING CHANGE`)
6. Footer values MAY contain spaces and newlines; parsing terminates when the next valid footer token/separator pair is observed
### Breaking changes
7. Breaking changes MUST be indicated by a `!` immediately before the `: ` in the type/scope prefix, OR as a `BREAKING CHANGE:` footer entry (or both). A `BREAKING CHANGE` footer MUST be uppercase text followed by colon, space, and description. When `!` is used, the `BREAKING CHANGE:` footer MAY be omitted. Breaking changes correlate with SemVer MAJOR
8. `BREAKING-CHANGE` MUST be synonymous with `BREAKING CHANGE` when used as a footer token
### Case sensitivity
9. All structural elements MUST NOT be treated as case sensitive, with the exception of `BREAKING CHANGE` which MUST be uppercase
## Scope Conventions
Use short, lowercase nouns that identify the section of the codebase:
- Module or feature area: `auth`, `api`, `billing`, `editor`
- Layer: `hooks`, `ui`, `domain`, `infra`
- App or package name in a monorepo: `frontend`, `functions`
Keep scopes consistent across the project — reuse existing scopes before inventing new ones.
## Examples
**Simple feature (preferred short form):**
feat: add user avatar upload
**Fix with scope:**
fix(api): prevent race condition in request handler
**Breaking change with `!` (short form):**
feat(auth)!: replace session-based auth with JWT
**Breaking change with `!` and footer (long form, when context is needed):**
feat(auth)!: replace session-based auth with JWT
BREAKING CHANGE: all endpoints now require Bearer token instead of session cookie
**Body for additional context (only when the description is not enough):**
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are obsolete now.
Refs: #123