Conventional Commits + Auto-Changelog Setup: A Practical Guide

As engineers, we're constantly striving for efficiency, clarity, and maintainability in our codebases. Yet, one area often overlooked, or at best, handled inconsistently, is the humble changelog. Manually curating a changelog for every release is a tedious, error-prone task that nobody enjoys. It's a prime candidate for automation.

This is where conventional commits, paired with an intelligent auto-changelog solution, come into play. It's not just about saving time; it's about creating a living, breathing history of your project that's useful to developers, product managers, and even end-users. If you're tired of "miscellaneous changes" in your release notes, read on.

The "Why" Behind Conventional Commits

Before we dive into automation, we need a standardized input. Conventional Commits provide exactly that. It's a lightweight convention on top of commit messages, defining a structured format that makes them human-readable and machine-parseable.

The core structure is simple:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]
  • type: Mandatory, describing the kind of change (e.g., feat, fix, docs, style, refactor, test, chore).
  • scope: Optional, providing contextual information about where the change was made (e.g., api, ui, auth, database).
  • description: Mandatory, a concise summary of the change.
  • body: Optional, for a longer explanation, motivations, or details.
  • footer(s): Optional, typically for referencing issues (e.g., Fixes #123) or indicating breaking changes (BREAKING CHANGE: ...).

Why bother?

  • Clarity: A quick glance at the commit history tells you exactly what kind of changes happened.
  • Automated Versioning: Tools can use commit types (especially feat and fix) to automatically determine semantic version bumps (major, minor, patch).
  • Automated Changelog Generation: This is the big one. Machines can parse these commits and group them into meaningful release notes.
  • Improved Collaboration: Everyone on the team understands the intent behind a commit.

Consider the difference: * git commit -m "update user logic" (vague) * git commit -m "feat(api): add user authentication endpoint" (clear, machine-readable) * git commit -m "fix(db): handle null values in user profile" (specific, indicates a bug fix)

Implementing Conventional Commits in Your Workflow

Adopting conventional commits requires a bit of team education and, ideally, some tooling to enforce the convention.

Getting Started

  1. Educate Your Team: The first step is to explain the "why" and "how" to your development team. Provide clear guidelines and examples.
  2. Update Your Commit Guidelines: Add conventional commit rules to your project's CONTRIBUTING.md or internal documentation.
  3. Tooling for Enforcement: This is crucial for consistency. Manual adherence often wanes over time.

Enforcement Tools: Commitlint & Husky

One of the most effective ways to enforce conventional commits is by using a combination of commitlint and Husky.

commitlint is a linter that checks if your commit messages meet the conventional commit specification. Husky is a tool that allows you to easily run Git hooks (like pre-commit, commit-msg, pre-push).

Here's how you might set it up in a JavaScript/Node.js project (the concepts apply broadly to other ecosystems with similar hook runners):

  1. Install Dependencies: bash npm install --save-dev @commitlint/config-conventional @commitlint/cli husky

    • @commitlint/config-conventional: The ruleset for conventional commits.
    • @commitlint/cli: The command-line interface for commitlint.
    • husky: To manage Git hooks.

  2. Configure commitlint: Create a commitlint.config.js file in your project root: javascript // commitlint.config.js module.exports = { extends: ['@commitlint/config-conventional'], // You can add custom rules here if needed rules: { 'scope-case': [2, 'always', 'camel-case'], // Example: enforce camelCase for scopes }, };

  3. Set up Husky Hook: Initialize Husky and add a commit-msg hook. This hook will run commitlint every time you attempt to commit. bash npx husky install npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}' Now, if you try to commit with a message like git commit -m "some random message", commitlint will catch it and prevent the commit, providing helpful feedback.

Common Commit Types

While the specification is flexible, these are widely accepted types:

  • feat: A new feature. Maps to a minor version bump.
  • fix: A bug fix. Maps to a patch version bump.
  • docs: Documentation only changes.
  • style: Changes that do not affect the meaning of the code (whitespace, formatting, semicolons, etc.).
  • refactor: A code change that neither fixes a bug nor adds a feature.
  • perf: A code change that improves performance.
  • test: Adding missing tests or correcting existing tests.
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation.
  • build: Changes that affect the build system or external dependencies (example scopes: npm, webpack).
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).

Pitfalls and Edge Cases

  • Initial Friction: Teams might resist adopting a new standard. Emphasize the long-term benefits.
  • Legacy Commits: Don't try to rewrite history for old commits. Start fresh from a certain point. Your changelog tool should be able to handle this by only looking at commits from the last release.
  • Over-Scoping: Don't get bogged down in finding the "perfect" scope for every tiny change. Pragmatism is key.

Integrating Auto-Changelog Generation

Once your team consistently uses conventional commits, the path to automated changelogs is wide open. Auto-changelog tools parse your Git history, identify the conventional commit types, and then generate a structured changelog.

How Auto-Changelog Tools Work

These tools typically:

  1. Read your Git commit history, often from the last tag or release.
  2. Parse each commit message according to the conventional commit specification.
  3. Group commits by type (feat, fix, refactor, etc.).
  4. Format them into a human-readable Markdown file, often categorizing by type and including links to PRs or issues.
  5. Automatically determine the next semantic version based on the commit types (feat -> minor, fix -> patch, BREAKING CHANGE -> major).

Choosing a Tool

You have options, from open-source CLIs to integrated SaaS solutions.

1. Open-Source CLIs (e.g., conventional-changelog-cli)

For local generation or integrating into a simple CI/CD pipeline, tools like conventional-changelog-cli are powerful.

  • Installation: bash npm install -g conventional-changelog-cli
  • Usage Example: To generate a changelog and append it to CHANGELOG.md: bash conventional-changelog -p angular -i CHANGELOG.md -s -r 0 This command uses the angular preset (a common conventional commit style), appends to CHANGELOG.md, and keeps the file in place (-s for same-file).

Limitations of CLI-based solutions:

  • **CI/CD