Commit Message Convention Template

Commit message standard: Conventional Commits structure, types and SemVer effect, scopes, breaking changes, footers and trailers, examples, commitlint and release tooling

소프트웨어 및 엔지니어링표준Conventional Commits 1.0.0; SemVer 2.0.0commit message convention업데이트됨 2026. 10. 29.

에디터에서 열기.md 다운로드

사용법: Use it when a team wants consistent commit history that drives versions and changelogs. Fill the scope list from the real code layout and decide where the rule is enforced first. The main pitfall is hiding a breaking change in a refactor or chore commit.

미리보기

Commit Message Convention: [Repository or organisation]

Team standard for writing commit messages: the message structure, allowed types and scopes, how to mark breaking changes, footers and trailers, how commits map to version numbers and changelogs, and the tooling that checks the rules. Based on Conventional Commits 1.0.0 (conventionalcommits.org, checked 30 October 2026) and its mapping to Semantic Versioning 2.0.0. Replace every [bracketed] value and every line marked Example. Worked examples use Brindlemark, a fictional open-source Markdown editor.

Document control

Field	Value
Document ID	[CMC-STD-001]
Version	[1.0]
Status	[Draft / Approved]
Owner	[@tech-lead]
Applies to	[Example: All repositories in the `brindlemark` organisation]
Enforced on	[Example: Pull request titles, checked in CI before squash merge]
Last updated	YYYY-MM-DD

Revision history

Version	Date	Author	Change
1.0	YYYY-MM-DD	[@name]	First version
1.1	YYYY-MM-DD	[@name]	Example: Added `i18n` scope

1. Message structure

<type>[optional scope][optional !]: <description>

[optional body]

[optional footer(s)]

Part	Rule
Type	A noun from the list in section 3, followed by an optional scope in parentheses, an optional `!`, a colon and a space
Description	A short summary in the imperative mood ("add", not "added"), no full stop at the end, [Example: at most 72 characters for the whole first line]
Body	Optional; starts after one blank line; explains why the change was made and what it affects; may have several paragraphs
Footers	Optional; start after one blank line; each is a token, a separator (`:` or `#`) and a value; tokens use `-` instead of spaces

The 72-character limit and the imperative mood are team rules, not part of Conventional Commits; they keep messages readable in git log --oneline and in hosting interfaces.

2. Breaking changes

Mark a breaking change in one or both of these ways:

Add ! right before the colon: feat(api)!: remove the legacy export endpoint.
Add a footer that starts with BREAKING CHANGE: (upper case, or BREAKING-CHANGE:) followed by a description of what breaks and how to migrate.

Use both when the migration needs explaining: the ! makes it visible in one-line logs and the footer carries the detail into the changelog. Any type can be breaking, not only feat.

3. Types

Type	Use for	Version effect	In changelog
`feat`	A new feature for users	MINOR	Yes, "Added"
`fix`	A bug fix for users	PATCH	Yes, "Fixed"
`perf`	A change that improves performance without changing behaviour	PATCH [team choice]	Yes, "Changed"
`refactor`	Code change that neither fixes a bug nor adds a feature	None	No
`docs`	Documentation only	None	No
`test`	Adding or correcting tests	None	No
`build`	Build system or dependency changes	None, unless user-facing	[Team choice]
`ci`	CI configuration and scripts	None	No
`style`	Formatting with no code meaning change	None	No
`chore`	Maintenance that fits no other type	None	No
`revert`	Reverts an earlier commit; footer `Refs:` lists the reverted hashes	Depends on the reverted change	Yes

Any type with ! or a BREAKING CHANGE footer means a MAJOR version bump (after 1.0.0).

4. Scopes

Scope	Covers	Owner
Example: `editor`	`src/editor/`	[@editor-team]
Example: `preview`	`src/preview/`, renderers	[@preview-team]
Example: `storage`	`src/storage/`, migrations	[@platform-team]
Example: `i18n`	`messages/`	[@docs-team]
Example: `deps`	Dependency updates	[@platform-team]
[scope]	[Paths]	[@owner]

Leave the scope out when a change spans many areas; do not invent a scope for one commit.

5. Footers and trailers

Footer	When	Example
`BREAKING CHANGE:`	Any breaking change	`BREAKING CHANGE: config key "theme" is now "appearance"`
`Refs:`	Link issues or reverted commits	`Refs: #482`
`Closes`	Close an issue on merge (hosting-platform keyword)	`Closes #482`
`Signed-off-by:`	Projects that require the Developer Certificate of Origin; added by `git commit -s`	`Signed-off-by: [Name] <[email]>`
`Co-authored-by:`	Credit a co-author on hosting platforms that support it	`Co-authored-by: [Name] <[email]>`
[Example: `AI-Assisted:`]	When the AI Coding Assistant Policy (`dev/ai-coding-assistant-policy`) asks for provenance	`AI-Assisted: TOOL-002 session 7f3c2a`

6. Examples

Each block below is one complete commit message.

A feature with a scope:

feat(preview): render footnotes in the side panel

A fix with a body and a closing footer:

fix(storage): keep unsaved edits when the tab is restored

Autosave raced with restore and overwrote the newer draft.
Restore now compares revision numbers before writing.

Closes #482

A breaking change marked both ways:

feat(api)!: remove the v1 export endpoint

BREAKING CHANGE: /api/v1/export is gone. Call /api/v2/export, which
returns the same document with front matter kept.

A revert that names the reverted commit:

revert: feat(preview): render footnotes in the side panel

Refs: 3f9c2e1

A documentation change with no scope:

docs: explain offline mode in the README

7. Tooling and enforcement

Stage	Tool option	What it does
Writing	Commitizen (cz-cli or commitizen-tools), editor plugins	Prompts for type, scope and description
Local check	commitlint with the conventional configuration, run from a commit-msg hook	Rejects messages that break the rules before push
CI check	commitlint or a pull request title check	Blocks merge when the title, or each commit, breaks the rules
Versioning	semantic-release, release-please, Cocogitto or commitizen-tools	Calculates the next version from commit types
Changelog	conventional-changelog or git-cliff	Groups commits into release notes for the Changelog (`dev/changelog`)

[Example: Brindlemark squash-merges every pull request, checks the title with commitlint in CI, and lets release-please open the release pull request with the version bump and changelog.]

A minimal commitlint configuration file (commitlint.config.js) that extends the conventional rules and restricts scopes to the list in section 4:

export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'scope-enum': [2, 'always', ['editor', 'preview', 'storage', 'i18n', 'deps']],
    'header-max-length': [2, 'always', 72],
  },
};

8. Exceptions and fixes

Before merge: fix the message with git commit --amend or by editing the pull request title.
After merge to a protected branch: do not rewrite history. Correct the changelog entry by hand, or add an empty commit only if your release tool needs it, following Branching Strategy (dev/branching-strategy).
Merge commits and automated dependency commits may use the tool's own format if the CI check is configured to allow it.

Standard and licence note

Based on Conventional Commits 1.0.0 (conventionalcommits.org, specification licensed CC BY 3.0) and Semantic Versioning 2.0.0 (semver.org, CC BY 3.0), cited by name and rule; the rules are paraphrased, not copied. The type list follows the conventional configuration of commitlint as named on the Conventional Commits site; tool names belong to their projects. Subject length, scopes and the AI-Assisted trailer are team choices, not part of the specification. Brindlemark is fictional. Template licence: MIT.