20+ Syntax Rules

Conventional Commits & Semantic Versioning Matrix

The definitive Conventional Commits specification cheat sheet: commit types, scopes, breaking change syntax, automated changelog generation, and SemVer rules with 1-click copy.

Commit Types (8 commands)

Commit Types

feat: add user dark mode toggle and persistence

Introduces a new user-facing feature or API capability to the codebase.

PRO TIP Triggers a MINOR semantic version bump (e.g. 1.2.0 -> 1.3.0) in automated release pipelines.

Commit Types

fix: resolve race condition in token refresh loop

Patches a bug, regression, or crash in production code.

PRO TIP Triggers a PATCH semantic version bump (e.g. 1.2.0 -> 1.2.1) in automated release pipelines.

Commit Types

chore: bump dependencies and remove deprecated polyfills

Routine maintenance, dependency updates, and tooling tasks that do not affect production logic.

PRO TIP Does not trigger a version bump by default; excluded from user-facing CHANGELOGs.

Commit Types

refactor: simplify database connection pool retry logic

Code refactoring that neither fixes a bug nor adds a user feature.

PRO TIP Improves maintainability, readability, or structure without changing external behavior.

Commit Types

perf: replace regex parser with streaming lexer

Performance optimization that speeds up execution or reduces memory usage.

PRO TIP Document benchmark metrics in the commit body to prove performance delta.

Commit Types

docs: update OpenAPI specification and README quickstart

Documentation updates, code comments, and API schema corrections.

PRO TIP Keep separate from code commits to streamline documentation PR reviews.

Commit Types

test: add integration test suite for payment webhooks

Adding missing unit tests, integration suites, or mock fixtures.

PRO TIP Does not alter application code; ensures test coverage metrics are met in CI.

Commit Types

ci: update GitHub Actions Node.js matrix to include v22

Modifications to CI/CD pipeline configuration, Dockerfiles, and runner scripts.

PRO TIP Use when adjusting workflow triggers, secrets caching, or deployment actions.

Scopes & Breaking Changes (3 commands)

Scopes & Breaking Changes

feat(auth)!: replace session cookies with JWT bearer tokens

BREAKING CHANGE: The /api/login endpoint no longer returns Set-Cookie headers. Clients must supply Authorization: Bearer <token>.

The exclamation mark (!) after scope denotes an incompatible API breaking change.

PRO TIP Triggers a MAJOR version bump (e.g. 1.3.0 -> 2.0.0). Always document migration guide in footer.

Scopes & Breaking Changes

fix(parser): prevent infinite loop on malformed JSON payload

Specifies the sub-package or component affected inside parentheses (scope).

PRO TIP Common scopes include: (api), (ui), (auth), (database), (cli), (docs).

Scopes & Breaking Changes

refactor(db): migrate user table ID column from UUIDv4 to UUIDv7

Scoped refactoring explaining exact subsystem undergoing modernization.

PRO TIP Scopes make commit logs and Git Blame much easier to filter and audit.

Semantic Versioning (3 commands)

Semantic Versioning

MAJOR (X.0.0) -> BREAKING CHANGE or feat!

Incremented when incompatible API changes or breaking contract alterations are introduced.

PRO TIP Requires consumers to update code or change integration methods before upgrading.

Semantic Versioning

MINOR (0.X.0) -> feat

Incremented when backwards-compatible new features or optional parameters are added.

PRO TIP Existing client code continues working without code modifications.

Semantic Versioning

PATCH (0.0.X) -> fix

Incremented when backwards-compatible bug fixes and security patches are released.

PRO TIP Safe for automated continuous delivery patch updates.

Tooling & CI Automation (3 commands)

Tooling & CI Automation

npx commitlint --from=HEAD~1

Lints the latest Git commit message against Conventional Commits specification rules.

PRO TIP Install @commitlint/config-conventional and run inside husky git commit-msg hook.

Tooling & CI Automation

npx standard-version --release-as minor

Automatically tags Git release, bumps package.json version, and compiles CHANGELOG.md.

PRO TIP Parses all commit messages since last tag to group features, fixes, and breaking changes.

Tooling & CI Automation

git log --oneline --grep="^feat" -n 10

Filters Git commit history to display only feature commits matching Conventional Commits format.

PRO TIP Quickly audit features delivered in a sprint or release milestone.