Guidelines for Writing Effective Commit Messages and Code Review Annotations

Effective commit messages act as public documentation that helps reviewers quickly understand the intent of a change, generate reliable CHANGELOGs, filter irrelevant modifications, and provide richer context when browsing history.

Purpose (Why)

Enable reviewers to assess intent versus implementation.

Allow automated CHANGELOG generation.

Identify or ignore trivial changes such as formatting.

Provide useful information when browsing commit history.

Commit Message Format

A commit message consists of three sections separated by a blank line:

Subject line – a single line containing <type> , optional <scope> , and a brief description. It must use imperative present tense, start with a capital letter, and end without punctuation.

Body – explains the motivation, details of the change, and any performance benchmarks. It should also include a TestPlan section describing how the change is verified.

Footer – optional Relnote and associated ticket numbers (e.g., story:#12345 , Bug:#56789 ).

Type values (required, one only)

revert – revert a previous commit.

feat – add a new feature.

fix – fix a bug.

docs – documentation changes.

refactor – code refactoring without new functionality.

test – add or modify tests.

chore – routine tasks such as script maintenance.

style – formatting, whitespace, or comment changes that do not affect logic.

Scope (optional) – indicates the module or component (e.g., calendar, comment, video). When used, wrap it in parentheses and prepend with $ (e.g., $ (video) ).

Subject writing rules

Use imperative mood and present tense (e.g., "change" not "changed").

Capitalize the first word if it is English.

Separate the type/scope from the description with a colon and a space.

Body requirements

Explain the purpose, mechanism, and any performance impact.

Include a TestPlan paragraph with one of the following verification methods:

Automated verification (e.g., mvn test ).

Manual verification steps.

"eyes" – simple changes that need extra reviewer attention.

TIP – test in production.

Footer details

Relnote – a single line keyword followed by the changelog entry, no blank line between them.

Associated tickets – list the relevant work items using formats like story:#12345 , Bug:#56789 , or issue:#23456 . Typically only one ticket is linked per commit.

Revert commits

When reverting, start the subject with revert: followed by the original subject, and in the body note the hash of the commit being reverted (e.g., 本次Revert的提交是 ). Automated tools should handle this pattern.

Following these conventions ensures that commit messages serve as clear, searchable documentation, improve review efficiency, and support automated tooling for changelog generation and release management.