Conventional Commits

Conventional Commits - Structured Commit Messages

Use this skill when writing commit messages, setting up commit linting, or implementing automated versioning and changelog generation based on the Conventional Commits specification.

When to Use

• Writing a new commit message and need the correct format
• Setting up commitlint or husky for commit validation
• Configuring semantic-release or standard-version for automated versioning
• Generating or reviewing a CHANGELOG.md

Philosophy

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages.

Core benefits:

• Automated versioning - Determine semantic version bumps (major/minor/patch)
• Automated changelogs - Generate CHANGELOG.md from commit history
• Better history - Structured, searchable, filterable commit log
• Clear communication - Team understands impact of changes
• Tooling integration - CI/CD can act on commit types

Key principle: Commit messages are not just history—they're documentation and automation triggers.

Specification Overview

Basic Structure

[optional scope]: 

[optional body]

[optional footer(s)]

Simple Example

feat(auth): add JWT token refresh endpoint

Complete Example

feat(auth)!: migrate to OAuth 2.0

Replace custom authentication with OAuth 2.0 standard.
This improves security and enables SSO integration.

BREAKING CHANGE: API endpoints /login and /logout have been removed.
Use /oauth/authorize and /oauth/token instead.

Closes #123
Refs #456

Commit Message Components

1. Type (Required)

Format: ``

Purpose: Describes the category of change.

Standard types:

| Type | Description | Version Bump | Changelog Section | |------|-------------|--------------|-------------------| | feat | New feature | MINOR (0.x.0) | Features | | fix | Bug fix | PATCH (0.0.x) | Bug Fixes | | docs | Documentation only | PATCH | Documentation | | style | Code style (formatting, whitespace) | None | None | | refactor | Code refactoring (no behavior change) | None | None | | perf | Performance improvement | PATCH | Performance | | test | Adding/updating tests | None | None | | build | Build system or dependencies | None | Build System | | ci | CI/CD configuration | None | CI | | chore | Maintenance tasks | None* | Chores | | revert | Reverts a previous commit | Depends | Reverts |

*Version bump behavior depends on configuration

Examples:

feat: add user profile page
fix: resolve memory leak in data processor
docs: update installation guide
style: format code with prettier
refactor: extract validation logic to separate module
perf: optimize database queries
test: add unit tests for auth service
build: upgrade webpack to v5
ci: add Docker build step
chore: update dependencies
revert: revert "feat: add experimental feature"

2. Scope (Optional)

Format: ()

Purpose: Specifies the area of codebase affected.

Common scopes (project-dependent):

For web applications:

feat(auth): add password reset
feat(ui): update button styles
feat(api): add rate limiting
feat(db): add user index

For libraries:

fix(parser): handle edge case in JSON parsing
feat(compiler): add source map generation
docs(api): document new methods

For monorepos:

feat(web): add landing page
fix(mobile): resolve crash on Android
chore(deps): update shared dependencies

Scope naming conventions:

• Lowercase
• Short (1-2 words)
• Consistent across team
• Match project structure (e.g., module names)

Multiple scopes:

feat(api,ui): add user search functionality

No scope (when change is global):

chore: update Node.js version
docs: update README

3. Description (Required)

Format: [scope]:

Rules:

• Lowercase first letter (unless proper noun)
• No period at the end
• Imperative mood ("add" not "added" or "adds")
• Concise ([scope]!: or BREAKING CHANGE:` in footer

Purpose: Signals a breaking change that requires major version bump.

Method 1: ! after type/scope:

feat(api)!: change response format to JSON:API spec

Method 2: BREAKING CHANGE: footer:

feat(api): update user endpoint

BREAKING CHANGE: Response format changed to JSON:API specification.
Old format: { user: {...} }
New format: { data: { type: "user", attributes: {...} } }

Method 3: Both (recommended for clarity):

feat(api)!: change response format to JSON:API spec

BREAKING CHANGE: Response format changed. See migration guide.

Breaking change guidelines:

• Always include in footer when using !
• Explain what broke and how to migrate
• Consider adding migration guide link
• Use for incompatible API changes

5. Body (Optional)

Format: Blank line after description, then body text.

Purpose: Provides context, motivation, and implementation details.

When to include:

• Complex changes that need explanation
• Non-obvious implementation decisions
• Context for "why" not just "what"
• Breaking changes details

Structure:

• Use imperative mood (like description)
• Wrap at 72 characters
• Multiple paragraphs allowed (separated by blank lines)
• Can include bullet points

Example:

refactor(auth): migrate from JWT to session-based auth

Session-based authentication provides better security for our
use case since we can invalidate sessions server-side. JWTs
cannot be invalidated without maintaining a blocklist.

Implementation notes:
- Redis used for session storage
- Session TTL set to 24 hours
- Auto-renewal on activity

6. Footer (Optional)

Format: Blank line after body, then footer(s).

Purpose: References, breaking changes, co-authors.

Common footers:

Issue references:

Closes #123
Fixes #456
Resolves #789
Refs #101

Breaking changes:

BREAKING CHANGE: API endpoint /users renamed to /accounts

Co-authors:

Co-authored-by: Jane Doe 
Co-authored-by: John Smith 

Reviewed by:

Reviewed-by: Alice 

Complete example with multiple footers:

feat(api)!: change authentication flow

Migrate from basic auth to OAuth 2.0 for better security
and third-party integration support.

BREAKING CHANGE: /login endpoint removed. Use /oauth/authorize instead.
Closes #234
Refs #189
Co-authored-by: Jane Doe 

Full Examples

Feature Addition

feat(checkout): add guest checkout option

Allow users to complete purchases without creating an account.
Guest users receive order confirmation via email and can track
orders using order number and email combination.

Closes #145

Bug Fix

fix(payment): resolve double charge issue

Prevent duplicate payment processing when user clicks
"Pay Now" multiple times. Added request deduplication
using idempotency keys.

Fixes #892

Breaking Change

feat(api)!: migrate to GraphQL

Replace REST API with GraphQL for better flexibility
and reduced over-fetching.

BREAKING CHANGE: All REST endpoints under /api/v1 have been
removed. Use GraphQL endpoint at /graphql instead.
See migration guide: docs/migration-v2.md

Closes #567

Documentation

docs(readme): add Docker deployment guide

Include step-by-step instructions for deploying the application
using Docker Compose, including environment variables and
volume configuration.

Refactoring

refactor(database): extract repository pattern

Move database queries from controllers to repository classes
for better separation of concerns and testability.

No functional changes.

Performance Improvement

perf(search): optimize full-text search queries

Replace LIKE queries with full-text search indexes.
Reduces average search time from 800ms to 50ms.

Refs #234

Dependency Update

build(deps): upgrade React to v18

Update React and React DOM to v18 for concurrent rendering
features and automatic batching improvements.

BREAKING CHANGE: React 18 requires Node.js >= 14

CI/CD Change

ci: add automated security scanning

Integrate Snyk to scan for vulnerabilities on every PR.
Build fails if high-severity issues are detected.

Revert

revert: revert "feat(search): add fuzzy matching"

This reverts commit a1b2c3d4e5f6.

Fuzzy matching caused performance degradation on large datasets.
Will reimplement with optimized algorithm in future PR.

Refs #789

Commit Message Guidelines

1. Atomic Commits

One logical change per commit:

✅ Good (atomic):

fix(auth): resolve login redirect loop
feat(profile): add avatar upload
test(auth): add login flow tests

❌ Bad (mixed changes):

feat(profile): add avatar upload, fix login bug, update tests

2. Imperative Mood

Use present tense, imperative mood:

✅ Good:

add user authentication
fix memory leak
update dependencies
remove deprecated method

❌ Bad:

added user authentication  (past tense)
fixes memory leak          (present tense)
updating dependencies      (gerund)
removed deprecated method  (past tense)

Why imperative? It matches Git's own convention:

• git merge → "Merge branch 'feature'"
• git revert → "Revert 'commit message'"

3. Describe WHAT and WHY, Not HOW

✅ Good:

perf(api): optimize user query performance

Reduce average response time from 800ms to 50ms by adding
database indexes on frequently queried fields.

❌ Bad:

perf(api): add indexes to users table on email and created_at columns

(Focuses on HOW, not WHAT/WHY)

4. Length Guidelines

Description:

• 50-72 characters (hard limit: 72)
• One line summary

Body:

• Wrap at 72 characters
• Explain context and motivation
• Multiple paragraphs allowed

Example:

feat(auth): add OAuth 2.0 support                     parsed.header.includes('!') ? 20 : 0
    ]
  }
}

Husky + commitlint

Purpose: Run commitlint on every commit.

Installation

npm install --save-dev husky
npx husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

Add to package.json

{
  "scripts": {
    "prepare": "husky install"
  }
}

Now every commit will be linted!

Commitizen

Purpose: Interactive CLI for writing conventional commits.

Installation

npm install --save-dev commitizen cz-conventional-changelog
npx commitizen init cz-conventional-changelog --save-dev --save-exact

Configuration

// package.json
{
  "scripts": {
    "commit": "cz"
  },
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  }
}

Usage

git add .
npm run commit

Interactive prompts:

? Select the type of change: (Use arrow keys)
❯ feat:     A new feature
  fix:      A bug fix
  docs:     Documentation only changes
  ...

? What is the scope of this change: (press enter to skip)
  auth

? Write a short description:
  add two-factor authentication

? Provide a longer description: (press enter to skip)
  

? Are there any breaking changes?
  No

? Does this change affect any open issues?
  Closes #123

Custom Commitizen Adapter

For custom prompts:

npm install --save-dev cz-customizable

// .cz-config.js
module.exports = {
  types: [
    { value: 'feat', name: 'feat:     A new feature' },
    { value: 'fix', name: 'fix:      A bug fix' },
    { value: 'docs', name: 'docs:     Documentation changes' },
    { value: 'style', name: 'style:    Code style changes' },
    { value: 'refactor', name: 'refactor: Code refactoring' },
    { value: 'perf', name: 'perf:     Performance improvements' },
    { value: 'test', name: 'test:     Add or update tests' },
    { value: 'build', name: 'build:    Build system changes' },
    { value: 'ci', name: 'ci:       CI/CD changes' },
    { value: 'chore', name: 'chore:    Other changes' }
  ],

  scopes: [
    { name: 'auth' },
    { name: 'api' },
    { name: 'ui' },
    { name: 'db' },
    { name: 'deps' }
  ],

  scopeOverrides: {
    feat: [
      { name: 'auth' },
      { name: 'api' },
      { name: 'ui' }
    ]
  },

  messages: {
    type: 'Select the type of change:',
    scope: 'Select the scope:',
    subject: 'Write a short description:\n',
    body: 'Provide a longer description (optional):\n',
    breaking: 'List any breaking changes (optional):\n',
    footer: 'List any issues closed (e.g., #123, #456):\n',
    confirmCommit: 'Confirm commit?'
  },

  allowCustomScopes: true,
  allowBreakingChanges: ['feat', 'fix'],
  subjectLimit: 72
}

Automated Versioning

semantic-release

Purpose: Fully automated versioning and changelog generation.

Installation

npm install --save-dev semantic-release

Configuration

// package.json
{
  "scripts": {
    "semantic-release": "semantic-release"
  },
  "release": {
    "branches": ["main"],
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      "@semantic-release/changelog",
      "@semantic-release/npm",
      "@semantic-release/github",
      "@semantic-release/git"
    ]
  }
}

GitHub Actions

# .github/workflows/release.yml
name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - run: npm ci
      
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

What it does:

1. Analyzes commits since last release
2. Determines version bump (major/minor/patch)
3. Generates changelog
4. Creates git tag
5. Publishes to npm
6. Creates GitHub release

standard-version

Purpose: Manual versioning with conventional commits.

Installation

npm install --save-dev standard-version

Configuration

// package.json
{
  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:major": "standard-version --release-as major"
  },
  "standard-version": {
    "types": [
      { "type": "feat", "section": "Features" },
      { "type": "fix", "section": "Bug Fixes" },
      { "type": "chore", "hidden": true },
      { "type": "docs", "section": "Documentation" },
      { "type": "style", "hidden": true },
      { "type": "refactor", "section": "Code Refactoring" },
      { "type": "perf", "section": "Performance Improvements" },
      { "type": "test", "hidden": true }
    ]
  }
}

Usage

# Automatic version bump
npm run release

# Specific version bump
npm run release:minor
npm run release:major

# Preview without committing
npm run release -- --dry-run

# Push release
git push --follow-tags origin main

What it does:

1. Bumps version in package.json
2. Generates CHANGELOG.md
3. Commits changes
4. Creates git tag

Version Bump Rules

Based on commit types:

| Commit Type | Version Bump | Example | |-------------|--------------|---------| | feat | MINOR (0.x.0) | 1.2.0 → 1.3.0 | | fix | PATCH (0.0.x) | 1.2.0 → 1.2.1 | | perf | PATCH (0.0.x) | 1.2.0 → 1.2.1 | | ! or BREAKING CHANGE | MAJOR (x.0.0) | 1.2.0 → 2.0.0 | | docs, style, refactor, test, chore | No bump* | - |

*Configurable based on tool settings

Pre-1.0.0 versions:

• BREAKING CHANGE → MINOR (0.x.0)
• feat → MINOR (0.x.0)
• fix → PATCH (0.0.x)

Changelog Generation

Automatic Generation

With semantic-release:

Changelog generated automatically on release:

# Changelog

## [2.0.0](https://github.com/user/repo/compare/v1.2.0...v2.0.0) (2025-02-

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [brpaz](https://github.com/brpaz)
- **Source:** [brpaz/agent-skills](https://github.com/brpaz/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.