Conventional Commits: Stop Writing Useless Git Messages Forever

Your commit history is a mess. I've seen teams waste hours digging through 'fixed stuff' and 'updated code' trying to find when a bug was introduced. That's not just annoying — it's dangerous when you need to revert a change in production at 2 AM. Conventional Commits fixes this by giving every commit a structured, meaningful label.

The problem it solves is simple: unstructured commit messages are useless for automation. Without a standard, you can't auto-generate changelogs, you can't automatically determine the next semantic version, and you can't easily filter commits by type. Teams end up manually curating release notes — a tedious, error-prone process.

By the end of this, you'll be able to write Conventional Commits from memory, set up a commitlint hook to enforce them, and integrate with semantic-release to automate versioning and changelogs. You'll never look at a 'fixed bug' commit the same way again.

The Anatomy of a Conventional Commit

Before we dive into tooling, you need to understand the format. It's dead simple: <type>(<scope>): <description>. The type is mandatory. Scope is optional but recommended. Description is a short summary in imperative mood. Then you can add a body and footer after a blank line.

Here's the full structure: ``` <type>(<scope>): <description>

[optional body]

[optional footer(s)] ```

The key types are: feat (new feature), fix (bug fix), chore (maintenance), docs (documentation), style (formatting), refactor (code change that neither fixes nor adds), test (adding tests), perf (performance improvement).

Breaking changes are indicated by appending ! after the type/scope, or by adding BREAKING CHANGE: in the footer. This triggers a major version bump in semantic versioning.

// io.thecodeforge — DevOps tutorial

# Good examples
git commit -m "feat: add user authentication"
git commit -m "fix(api): handle null pointer in user fetch"
git commit -m "feat!: drop support for Node 10"
git commit -m "fix: correct typo in email template

Closes #42"

# Bad examples (avoid these)
git commit -m "fixed bug"
git commit -m "update"
git commit -m "wip"

Why Bother? The Automation Payoff

The real value of Conventional Commits isn't just readability — it's automation. Once your commits are structured, tools can parse them to:

1. Auto-generate changelogs: Tools like standard-version or semantic-release scan your git log, group commits by type, and produce a beautiful CHANGELOG.md.
2. Automate semantic versioning: Based on the commits since the last release, the tool determines if it's a patch (fix), minor (feat), or major (breaking change) and bumps the version accordingly.
3. Filter commits for release notes: You can easily see all features, fixes, or breaking changes in a release.

Without this, you're manually curating release notes — a task that gets skipped or done poorly. I've seen teams forget to mention breaking changes, causing production outages when consumers don't update their code.

// io.thecodeforge — DevOps tutorial

# Install standard-version
npm install --save-dev standard-version

# Add to package.json scripts
# "release": "standard-version"

# Run release
npm run release

# This will:
# 1. Bump version in package.json based on commits
# 2. Generate/update CHANGELOG.md
# 3. Create a git tag
# 4. Commit the changes

Enforcing the Standard with Commitlint

You can't rely on everyone remembering the format. That's where commitlint comes in. It's a linter for commit messages. You hook it into your workflow via husky (Git hooks) so that every commit is validated before it's accepted.

Here's the setup: 1. Install commitlint and the conventional config. 2. Install husky and configure the commit-msg hook. 3. Write a commitlint.config.js file.

Now, if someone writes git commit -m "fixed bug", commitlint rejects it with a clear error message. The developer must rewrite it properly.

// io.thecodeforge — DevOps tutorial

# Install commitlint CLI and config
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# Create config file
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

# Install husky
npm install --save-dev husky

# Enable husky hooks
npx husky install

# Add commit-msg hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

# Now test it
git commit -m "fixed bug"
# Output: ⧗   input: fixed bug
# ✖   subject may not be empty [subject-empty]
# ✖   type may not be empty [type-empty]
# ✖   found 2 problems, 0 warnings

Semantic Versioning and Breaking Changes

This is powerful because it removes human judgment from versioning. The tool decides based on the commits. But you must be disciplined: if you mark a commit as feat but it's actually a breaking change, you'll accidentally release a minor version instead of major. I've seen this cause downstream breakage when consumers auto-update.

Always use ! for breaking changes. Example: feat!: remove deprecated login endpoint. This ensures the next version is major.

// io.thecodeforge — DevOps tutorial

# Correct breaking change commit
git commit -m "feat!: drop support for Node 10"

# Alternative with footer
git commit -m "feat: drop support for Node 10

BREAKING CHANGE: Node 10 is no longer supported."

# Both will trigger a major version bump

Scopes: When and How to Use Them

Scopes are optional but incredibly useful for large projects. They indicate the area of the codebase affected. Examples: feat(auth): add OAuth2 login, fix(api): handle timeout, chore(deps): update lodash.

Scopes should be nouns that map to modules, components, or layers. Keep them consistent. I recommend defining a list of allowed scopes in commitlint config to prevent typos.

When not to use scopes: if your project is small (single module), scopes add noise. Also, avoid overly granular scopes like fix(src/utils/helpers/string): fix typo — that's too specific. Stick to high-level areas.

// io.thecodeforge — DevOps tutorial

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'scope-enum': [2, 'always', ['auth', 'api', 'ui', 'deps', 'docs']]
  }
};

Integrating with CI/CD Pipelines

Enforcing commit messages locally is good, but you should also validate them in CI. This catches commits that bypass hooks (e.g., someone commits with --no-verify).

In GitHub Actions, you can use the commitlint action. In GitLab CI, run npx commitlint --from $CI_COMMIT_BEFORE_SHA --to $CI_COMMIT_SHA. This validates all commits in the push.

Here's a GitHub Actions workflow that runs on pull requests:

// io.thecodeforge — DevOps tutorial

name: Commitlint
on: [pull_request]

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
      - run: npm install
      - run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }}

When NOT to Use Conventional Commits

Conventional Commits is overkill for personal projects or small teams that don't release often. If you're the only developer and you never publish a package, the overhead of enforcing a standard isn't worth it.

Also, if your team is not bought in, forcing it will lead to resentment and bypasses. Start with a trial period on a new project, or introduce it alongside tooling that provides immediate value (like auto-changelog).

For monorepos, consider using tools like lerna or changesets that work with Conventional Commits but add scope management.