Conventional Commit

conventional-commit skill for programming & development

Category: development Source: github

What Is This?

Overview

Conventional Commits formats commit messages following a specification with type, scope, description, body, and footer sections. Types like feat, fix, docs, and refactor categorize changes. Scopes indicate which component changed. Breaking changes receive special markers. This structure enables automated changelog generation, semantic version determination, and commit filtering.

The format follows the pattern: type(scope): description, with optional body and footer. Tools parse this structure to generate release notes, determine the next version number, and filter commits by type or scope. Consistency across teams improves repository navigation and change understanding.

Who Should Use This

Development teams standardizing commit messages. Open source maintainers automating releases. DevOps engineers implementing semantic versioning. Technical leads enforcing code quality standards. Teams generating automated changelogs.

Why Use It?

Problems It Solves

Inconsistent commit messages make history difficult to navigate. Conventional commits enforce structure ensuring every commit communicates clearly.

Manual changelog creation consumes time reviewing commits. Conventional commit tools automatically generate changelogs from commit history, extracting features, fixes, and breaking changes into organized release notes.

Determining the next semantic version requires analyzing changes. With typed commits, tools automatically determine whether to increment the major, minor, or patch version based on commit types.

Conventional commit linters also catch malformed messages before merge, maintaining consistency across the entire history.

Core Highlights

Standardized commit message structure. Type prefixes categorizing change nature. Scope indicators for component context. Breaking change markers for API changes. Automated changelog generation. Semantic versioning automation. Commit message linting and validation.

How to Use It?

Basic Usage

Format commits with type, optional scope, and description. Use feat for features, fix for bugs, docs for documentation, and other standard types. Mark breaking changes with an exclamation mark or footer.

feat(auth): add OAuth2 login support
fix(api): correct pagination offset calculation
docs: update installation instructions
refactor(database): extract query builder

Specific Scenarios

For breaking changes, use an exclamation mark or footer.

feat(api)!: change response format to nested structure

fix(auth): update token expiration

BREAKING CHANGE: tokens now expire after 24 hours
instead of 7 days

For multi-paragraph explanations, use the body.

refactor(parser): improve error handling

Previous implementation threw generic errors making
debugging difficult. New approach provides specific
error types with context about parsing failures.

Closes #123

Real World Examples

A team implements conventional commits for their API project. After adoption, they configure commitlint to enforce format in pre-commit hooks, use standard-version to automatically generate changelogs, bump package versions based on commit types, and tag releases with generated notes. The release process drops from two hours of manual work to five minutes of automated execution.

An open source maintainer adds conventional commit guidelines to contributing documentation, configures GitHub Actions to validate pull request commits, and uses semantic-release for automated publishing. Contribution quality improves as contributors understand the expected format, and automated releases ensure version numbers match changes semantically.

A development team debugging production issues filters git history to show only fix type commits, narrows results by scope to find fixes in specific components, and uses commit messages to understand fix context without reading full diffs. Debugging time reduces substantially compared to unstructured commit history.

Advanced Tips

Use commitizen for interactive commit message creation guiding proper format. Configure commitlint in pre-commit hooks to catch issues early. Adopt semantic-release for fully automated versioning and publishing. Define custom scopes matching your project structure. Document project-specific conventions in contributing guidelines. Filter git log by type to understand change patterns.

When to Use It?

Use Cases

Open source projects with multiple contributors. Automated release and deployment pipelines. Projects requiring detailed changelogs. Semantic versioning implementation. Breaking change communication. Contribution guideline enforcement.

Important Notes

Requirements

Team agreement on conventional commit adoption. Git hooks or CI validation configured. Understanding of commit types and their meanings. Documentation of project-specific scopes. Tools like commitlint or commitizen installed.

Usage Recommendations

Start with basic types before adding custom ones. Document scopes clearly for team consistency. Use commitlint to enforce format automatically. Configure editor plugins for commit message assistance. Provide examples in contributing guidelines. Mark breaking changes explicitly to help consumers. Squash merge pull requests to maintain clean history.

Limitations

Requires discipline and tooling enforcement. Initial adoption has a learning curve. May feel verbose for simple changes. Tools must be configured and maintained. Does not replace clear commit descriptions. Team must agree on scope definitions.