Commit Message Convention Template

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

Revision history

1. Message structure

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

[optional body]

[optional footer(s)]

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

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

4. Scopes

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

5. Footers and trailers

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

[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.