Conventional Commits In software development, a clear project history isn’t just helpful—it’s essential. Conventional Commits is a lightweight specification that brings order to Git commit messages, making them readable for both humans and machines. This standard enables automatic changelog generation, semantic version bumps, and clearer team collaboration, transforming how development teams communicate changes.

What Are Conventional Commits and Why Do They Matter?

The Problem with Unstructured Commit Messages

Every developer has encountered a messy Git log filled with vague messages like “fixed stuff,” “updates,” or “WIP.” These unclear commit messages create several problems:

• Lost context: Six months later, no one remembers what “quick fix” actually fixed
• Difficult debugging: Finding when a bug was introduced becomes archaeological work
• Manual changelogs: Someone has to read through hundreds of commits to document releases
• Unclear versioning: Determining whether a release should be 1.1.0 or 2.0.0 becomes guesswork

Core Benefits for Developers and Teams

Conventional Commits solves these issues by providing structure. The key benefits include:

• Automatic CHANGELOG generation: Tools can parse commits and create release notes automatically
• Semantic version determination: The commit type directly indicates whether changes are patches, minor features, or breaking changes
• Better project communication: Team members and contributors immediately understand the nature of each change
• Trigger build and release processes: CI/CD pipelines can automatically deploy based on commit types
• Easier onboarding: New contributors can quickly understand project history and conventions
• Reproducible workflows: Particularly valuable in research and data science for tracking computational changes

How to Write a Conventional Commit: Syntax Explained

The Basic Commit Structure

Every Conventional Commit follows this format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The most basic example looks like this:

fix: resolve login button crash

Understanding Commit Types

The type communicates the intent of your change. Here are the standard types:

Type	Purpose	Version Impact
feat	A new feature	MINOR (0.x.0)
fix	A bug fix	PATCH (0.0.x)
docs	Documentation only changes	None
style	Code style changes (formatting, semicolons, etc.)	None
refactor	Code change that neither fixes a bug nor adds a feature	None
perf	Performance improvement	PATCH
test	Adding or updating tests	None
build	Changes to build system or dependencies	None
ci	Changes to CI configuration files	None
chore	Other changes that don’t modify src or test files	None

Decision Guide: When to use what?

• Choose feat when users will notice a new capability
• Choose fix when something broken now works correctly
• Choose refactor when you’re improving code structure without changing behavior
• Choose chore for maintenance tasks like updating dependencies
• Choose docs for README updates, comment improvements, or documentation sites
• Choose style for linting fixes, formatting changes, or whitespace adjustments

Using Optional Scopes for Context

Scopes provide additional context about what part of the codebase changed:

feat(parser): add support for nested JSON objects
fix(auth): prevent session timeout during file upload
docs(api): update authentication endpoint examples

Common scopes include component names, module names, or file paths. Keep them short and consistent across your project.

Crafting the Description and Body

The description is a brief summary (ideally under 72 characters) in present tense:

Good descriptions:

• add user profile export feature
• fix memory leak in image processing
• update installation instructions

Poor descriptions:

• Added stuff (too vague)
• Fixed the bug that was causing problems (not specific)
• Updated (missing context)

The optional body provides additional context:

feat: add dark mode toggle

Users can now switch between light and dark themes from the settings
page. The preference is saved in localStorage and persists across
sessions. This addresses the most requested feature from our user
survey.

Signaling Breaking Changes

Breaking changes are changes that make existing code incompatible. There are two ways to indicate them:

Method 1: Using ! after the type/scope:

feat!: remove deprecated API endpoints
refactor(auth)!: change token format from JWT to custom schema

Method 2: Using BREAKING CHANGE footer:

feat: update authentication flow

BREAKING CHANGE: The login endpoint now requires email instead of
username. Update all API calls to use email field.

Breaking changes trigger a MAJOR version bump (x.0.0) in semantic versioning.

Adding Footers for Metadata

Footers follow the git trailer format and provide structured metadata:

fix: prevent race condition in data sync

The sync process now uses a mutex to prevent concurrent writes to the
same resource.

Fixes #284
Reviewed-by: @senior-dev
Refs: #256, #312

Common footer types:

• Fixes #123 – Links to resolved issues
• Refs #456 – References related issues
• Reviewed-by: – Credits reviewers
• Co-authored-by: – Credits co-authors
• BREAKING CHANGE: – Describes breaking changes

Practical Examples and Real-World Scenarios

From Simple to Complex Commit Examples

Level 1: Simple fix

fix: correct typo in error message

Level 2: Feature with scope

feat(dashboard): add user activity graph

Level 3: Feature with body

feat(api): implement rate limiting

Add rate limiting middleware to prevent API abuse. Default limit is
100 requests per hour per IP address. Can be configured via
RATE_LIMIT_MAX environment variable.

Level 4: Breaking change with full context

refactor!: restructure configuration file format

BREAKING CHANGE: Configuration now uses YAML instead of JSON.
Migrate your config.json to config.yml using the provided
migration script: npm run migrate-config

The new format provides better readability and supports comments,
making it easier to document configuration options.

Refs #789

How to Handle Common Situations

When a commit fits multiple types: Choose the primary intent. If you’re adding a feature that also refactors existing code, use feat since that’s the main user-facing change.

Fixing a typo in a past commit message: Before pushing:

git commit --amend -m "fix: correct calculation in analytics"

After pushing (use with caution):

git rebase -i HEAD~3  # Rewrite last 3 commits

Linking to GitHub/GitLab issues:

fix: resolve data export timeout

Export process now streams data in chunks instead of loading
everything into memory.

Fixes #432
Related to #398

Grouping related changes: If you’re making several small fixes, you can either make separate commits or group them if they’re tightly related:

fix(ui): resolve multiple button styling issues

- Fix hover state on primary buttons
- Correct alignment in mobile navigation
- Update disabled state opacity

Fixes #112, #115, #119

Automating and Enforcing Conventional Commits

This is where Conventional Commits truly shines. The structured format enables powerful automation.

Essential Tools for the Ecosystem

Tool	Purpose	When to Use
commitlint	Validates commit messages against rules	Always – prevents bad commits from entering history
husky	Manages Git hooks easily	Use with commitlint to validate before commits
commitizen	Interactive CLI prompts for commit messages	Helpful for teams new to the convention
semantic-release	Automates versioning and changelog generation	Production projects that follow SemVer
standard-version	Manual alternative to semantic-release	When you want control over release timing

Setting Up Pre-commit Hooks with Husky

Install the necessary packages:

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky

Configure commitlint by creating commitlint.config.js:

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore']
    ]
  }
};

Set up Husky:

npx husky init
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

Now every commit will be validated. Invalid commits are rejected:

$ git commit -m "updated stuff"
⧗ input: updated stuff
✖ type must be one of [feat, fix, docs, ...] [type-enum]
✖ found 1 problems, 0 warnings

Integrating with CI/CD (GitHub Actions, GitLab CI)

GitHub Actions example:

Create .github/workflows/commitlint.yml:

name: Lint Commit Messages

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm install @commitlint/cli @commitlint/config-conventional
      
      - name: Validate PR commits
        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose

GitLab CI example:

Add to .gitlab-ci.yml:

commitlint:
  stage: test
  image: node:18
  before_script:
    - npm install @commitlint/cli @commitlint/config-conventional
  script:
    - npx commitlint --from="$CI_MERGE_REQUEST_DIFF_BASE_SHA" --to="$CI_COMMIT_SHA" --verbose
  only:
    - merge_requests

Generating Changelogs and Versioning with semantic-release

semantic-release automates the entire release workflow:

Install:

npm install --save-dev semantic-release

Create .releaserc.json:

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

Add to your GitHub Actions workflow:

- name: Release
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
  run: npx semantic-release

Now, every merge to main:

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

Adopting Conventional Commits in Your Team

Creating a Team Agreement or Contribution Guide

Add to your CONTRIBUTING.md:

## Commit Message Convention

We follow [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages.

### Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

### Allowed Types
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Code style changes (formatting, etc.)
- refactor: Code refactoring
- test: Adding or updating tests
- chore: Maintenance tasks

### Examples

feat(auth): add two-factor authentication fix: resolve memory leak in image processor docs: update API documentation

### Validation
All commits are automatically validated using commitlint. Invalid commit
messages will be rejected.

Strategies for Adopting in Existing Projects

Start from now: The easiest approach is to start using Conventional Commits for all new work without rewriting history:

# In your README
As of [date], this project uses Conventional Commits for all new changes.

Gradual migration:

1. Install and configure commitlint
2. Make it a warning (not error) initially
3. After 2-4 weeks, enforce strictly
4. Update documentation and onboard team

Clean slate approach (advanced): For smaller projects, you can rewrite history using interactive rebase, but this requires team coordination and force pushing.

Handling Edge Cases and FAQs

Do all contributors need to use it? For the best results, yes. However, if you use “Squash and Merge” on pull requests, the PR title becomes the commit message, so you only need to enforce the convention on PR titles.

Squash and merge workflows: When using GitHub’s “Squash and Merge,” make sure the PR title follows Conventional Commits format:

feat(api): add webhook support

All commits in the PR get squashed into one commit with this message.

Initial development phase: During rapid early development, some teams relax the rules temporarily. Consider using types like wip or init during bootstrapping, then switch to strict enforcement once the project stabilizes.

How to handle reverts: Git’s native revert creates messages like:

Revert "feat: add user export"

This reverts commit a1b2c3d4.

This is acceptable, though some teams prefix with revert: as a type.

Beyond the Basics: Advanced Patterns and Customization

Defining Your Own Custom Types

While the standard types cover most cases, teams can add custom types for their specific needs:

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        // Standard types
        'feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore',
        // Custom types for your team
        'security',  // Security fixes/improvements
        'deps',      // Dependency updates
        'i18n',      // Internationalization changes
        'a11y'       // Accessibility improvements
      ]
    ]
  }
};

Document your custom types clearly in your contribution guidelines.

The Relationship with Semantic Versioning (SemVer)

Conventional Commits maps directly to Semantic Versioning:

Commit Type	SemVer Impact	Example Version Change
fix:	PATCH	1.0.0 → 1.0.1
feat:	MINOR	1.0.0 → 1.1.0
BREAKING CHANGE: or !	MAJOR	1.0.0 → 2.0.0
Other types	No version bump	–

Multiple commits example: If a release includes:

• 3 fix: commits
• 2 feat: commits
• 1 docs: commit

The version bumps from 1.0.0 → 1.1.0 (MINOR takes precedence over PATCH)

If any commit has BREAKING CHANGE:, it becomes 2.0.0 (MAJOR overrides everything)

Case Study: Use in Scientific Reproducibility

The Long Term Ecological Research (LTER) network uses Conventional Commits to ensure reproducibility in data science workflows. Their approach demonstrates how the specification extends beyond traditional software:

Commit types for research code:

• data: – New dataset added or updated
• analysis: – Analysis script changes
• model: – Statistical model modifications
• viz: – Visualization updates
• doc: – Paper or report changes

Example from a research workflow:

feat(analysis): implement new species diversity metric

Add Shannon diversity index calculation to community analysis pipeline.
This provides a more robust measure than simple species counts for
sites with uneven abundance distributions.

Methods described in methods.md section 3.2.
Results stored in outputs/diversity_metrics.csv

Refs: research-plan.md#objective-4

This approach allows researchers to:

• Track exactly when analysis methods changed
• Link code changes to research objectives
• Auto-generate methods sections for papers
• Ensure computational reproducibility

Frequently Asked Questions

What is the simplest example of a Conventional Commit?

The absolute minimum is:

fix: resolve login button crash

Just type, colon, space, and a brief description.

What’s the difference between chore, docs, and style types?

Quick decision flowchart:

• Did you change documentation/README/comments? → docs:
• Did you only change formatting/whitespace/linting? → style:
• Did you update dependencies, config files, or other maintenance? → chore:

Do I have to use Conventional Commits from the start of a project?

No. Many projects adopt it mid-development. Start using it for new commits going forward. The structured messages will still provide value even if your early history is messy.

How do I enforce Conventional Commits in my GitHub repository?

The most reliable method is using GitHub Actions with commitlint (see the CI/CD section above). Alternatively, you can use a third-party GitHub app like Semantic Pull Requests which validates PR titles.

Can I use Conventional Commits with GitHub’s “Squash and Merge”?

Yes, and this is actually a popular approach. Configure your repository to squash commits on merge, then only enforce the convention on PR titles. The PR title becomes the commit message when squashed.

In your GitHub repository settings:

1. Enable “Squash merging”
2. Set default commit message to “Pull request title”
3. Use branch protection to require status checks from commitlint on PR titles

What if I make a mistake in my commit type before pushing?

If you haven’t pushed yet, use:

git commit --amend -m "feat: correct type for this commit"

If you’ve already pushed to a feature branch (not main):

git rebase -i HEAD~3  # Edit last 3 commits
# Change 'pick' to 'reword' for commits you want to fix

Avoid rewriting history on shared branches like main.

How are Conventional Commits used in data science or research projects?

Research projects use Conventional Commits to:

• Track methodology changes: Link code changes to specific research decisions
• Ensure reproducibility: Anyone can see exactly when and why analysis changed
• Generate methods sections: Auto-generate parts of research papers from commit history
• Manage data versions: Use types like data: to track dataset updates
• Coordinate teams: Clear communication in multi-investigator projects

This is especially valuable in fields like ecology, climate science, and computational biology where reproducibility is critical.

---

Conclusion

Conventional Commits transforms your Git history from a chaotic log into a structured, queryable database of changes. By following this specification, you enable powerful automation, clearer team communication, and better project maintainability.

READ MORE…