conventional-commits

name	conventional-commits
description	Guide for writing conventional commit messages. Use when committing changes, writing commit messages, or reviewing commit history.
license	BSD-3-Clause
metadata	{"author":"axone.xyz","version":"1.0"}

Conventional Commits

Commit Message Format

<type>(<scope>): <verb> <subject>

One line only. No body. No footer (except for breaking changes).

Subject Line Rules

• Imperative mood, present tense
• Short, dense, unambiguous
• Describes the intent, not the implementation
• One line only
• No capitalization at start
• No period at end

Verb Selection

⚠️ Avoid weak verbs: add, remove, change, update, modify

Use precise, action-oriented verbs:

Verb	Use When
enforce	Adding constraints or rules
introduce	Bringing in new concepts/APIs
implement	Building out functionality
prevent	Blocking undesired behavior
fix	Correcting bugs
refactor	Restructuring without behavior change
clarify	Improving readability/naming
align	Making consistent with standards
tighten	Strengthening validation/constraints
harden	Security or robustness improvements
validate	Input/state verification
handle	Managing edge cases
support	Enabling new use cases
ensure	Guaranteeing invariants
document	Documentation work

Type

Type	Description	Triggers
feat	New feature	Minor version bump
fix	Bug fix	Patch version bump
docs	Documentation only	No release
style	Formatting, whitespace	No release
refactor	Code restructuring	No release
perf	Performance improvement	Patch version bump
test	Adding/updating tests	No release
build	Build system, dependencies	No release
ci	CI/CD configuration	No release
chore	Maintenance tasks	No release

Scope

• Mandatory when it adds clarity
• Short, meaningful, domain or component oriented
• Use contract names without axone- prefix: gov, logic
• Other examples: workflow, dependabot, README, make, deps
• If unsure, omit it

Examples

See examples for comprehensive good and bad examples.

Quick reference:

feat(gov): introduce quadratic voting mechanism
fix(handlers): prevent overflow in vote counting
refactor(state): clarify storage key naming
test(gov): validate error paths for unauthorized access
build(deps): enforce abstract-sdk 0.26.1

Granularity

Rule: One commit = one intention

Instead of...	Prefer...
One big mixed commit	Multiple focused commits
feat: implement X and fix Y	Two separate commits
Tests bundled with feature	Separate test: commit
Build changes with feature	Separate build: commit

What to Avoid

• ❌ Generic messages hiding what changed
• ❌ Explanations or rationale in the message
• ❌ Marketing language or inflated wording
• ❌ Multiple intentions in one commit
• ❌ Vague subjects like "improve", "update", "fix issue"

Breaking Changes

Use ! after type/scope:

feat(msg)!: restructure ExecuteMsg variants
refactor(api)!: enforce stricter validation schema

Commit Linting

Commits are validated using commitlint. Ensuring lint passes is mandatory.

Validate locally:

npm i -g @commitlint/cli @commitlint/config-conventional
echo "feat(gov): introduce voting mechanism" | commitlint --extends @commitlint/config-conventional