By 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,logicOther examples:
workflow,dependabot,README,make,depsIf 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