Conventional Commits

Conventional Commits

Overview

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It provides a standardized format that enables automated tools to generate changelogs, determine semantic version bumps, and communicate the nature of changes clearly.

When to Use

Use this skill when:

• Creating git commits for any codebase
• Writing commit messages that need to follow a standard format
• The user mentions conventional commits, semantic versioning, or automated changelogs
• Working on projects that use automated release pipelines
• Contributing to open-source projects that require conventional commit format

Commit Message Format

[optional scope]: 

[optional body]

[optional footer(s)]

Required Elements

1. Type: A noun indicating the category of change
2. Description: A short summary of the change

Optional Elements

1. Scope: Context for the change (in parentheses)
2. Body: Detailed explanation (separated by blank line)
3. Footer(s): Metadata like breaking changes or issue references

Commit Types

Core Types (Semantic Versioning Impact)

| Type | Meaning | Version Bump | | ----------------------------------------------- | --------------- | ------------ | | feat | New feature | MINOR | | fix | Bug fix | PATCH | | feat! or feat with BREAKING CHANGE footer | Breaking change | MAJOR |

Additional Types (No Version Impact)

| Type | Meaning | | ---------- | ------------------------------------------------------- | | build | Build system or external dependencies | | chore | Maintenance tasks, no production code changes | | ci | CI/CD configuration and scripts | | docs | Documentation only changes | | style | Code style (formatting, semicolons, etc.) | | refactor | Code refactoring without fixing bugs or adding features | | perf | Performance improvements | | test | Adding or modifying tests | | revert | Reverting a previous commit |

Examples

Simple Commit

docs: update README with installation instructions

Commit with Scope

feat(api): add user authentication endpoint

Commit with Body

fix: prevent race condition in request handler

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Breaking Change (Footer Style)

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Breaking Change (Shorthand Style)

feat!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Multiple Footers

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Reviewed-by: Z
Refs: #123

Writing Good Descriptions

Do's

• Use imperative mood ("add" not "added" or "adds")
• Start with lowercase letter
• No period at the end
• Be concise but descriptive
• Explain WHAT and WHY, not HOW

Don'ts

• Don't use vague descriptions like "fix bug" or "update code"
• Don't include issue numbers in the description (use footer instead)
• Don't write long descriptions (use body instead)

Common Patterns

Feature Addition

feat(auth): implement OAuth2 login flow

Add support for OAuth2 authentication with Google and GitHub providers.
Includes token refresh logic and session management.

Closes #234

Bug Fix

fix(parser): handle empty input gracefully

Parser was throwing NullPointerException when receiving empty string.
Added null check and return empty result set instead.

Fixes #567

Breaking Change

refactor(api)!: rename user endpoints

BREAKING CHANGE: All /user/* endpoints renamed to /users/*
- /user/profile -> /users/profile
- /user/settings -> /users/settings

Migration guide: Update API client base paths

Documentation

docs(contributing): add PR submission guidelines

Add step-by-step guide for submitting pull requests including:
- Branch naming conventions
- Commit message format
- Required CI checks

Workflow Integration

Pre-commit Hooks

Use tools like commitlint to enforce conventional commit format:

{
  "extends": ["@commitlint/config-conventional"],
  "rules": {
    "type-enum": [
      2,
      "always",
      [
        "feat",
        "fix",
        "docs",
        "style",
        "refactor",
        "perf",
        "test",
        "build",
        "ci",
        "chore",
        "revert"
      ]
    ]
  }
}

Automated Changelog Generation

Tools like standard-version or semantic-release can automatically:

• Generate CHANGELOG.md from commit messages
• Bump version numbers based on commit types
• Create git tags and GitHub releases

CI/CD Integration

# Example GitHub Actions workflow
- name: Semantic Release
  uses: cycjimmy/semantic-release-action@v3
  with:
    semantic_version: 18
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Best Practices

1. One concern per commit: Each commit should address one issue or feature
2. Atomic commits: Commits should be self-contained and reversible
3. Write commits first: Draft commit messages before writing code
4. Use scopes wisely: Scopes should be consistent across the project
5. Reference issues: Use footers to link to issues, PRs, or tickets
6. Test before committing: Ensure tests pass before creating commits
7. Review your own diff: Always review changes before committing

Common Mistakes

| Mistake | Correction | | -------------------------- | ----------------------------------------- | | feat: Added new feature | feat: add new feature (imperative mood) | | feat: Add new feature. | feat: add new feature (no period) | | feat: Add New Feature | feat: add new feature (lowercase) | | feat(api,auth): ... | feat(api): ... (one scope) | | feat: fix bug | fix: fix bug (correct type) | | feat: add feature (#123) | Use footer: Refs: #123 |

Specification Compliance

This skill follows the Conventional Commits specification v1.0.0. For the complete specification, see: https://www.conventionalcommits.org/

Key rules from the specification:

1. Commits MUST be prefixed with a type
2. Type MUST be followed by a colon and space
3. Scope is OPTIONAL and enclosed in parentheses
4. Breaking changes MUST be indicated with ! or BREAKING CHANGE footer
5. Types other than feat and fix are allowed
6. The specification is case-insensitive except for BREAKING CHANGE

Quick Reference

[optional scope]: 

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Breaking: Add ! after type/scope OR add BREAKING CHANGE: footer

Version Impact: feat → MINOR, fix → PATCH, BREAKING CHANGE → MAJOR

Source & license

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

• Author: ntk148v
• Source: ntk148v/skills
• License: MIT

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