Conventional Commits

Conventional Commits
Name	Conventional Commits
Introduced	2015

Conventional Commits is a lightweight standardized convention for commit messages that prescribes a structured, machine-readable format for describing changes in version control systems. It aims to improve automation across release engineering, changelog generation, and continuous integration by defining clear semantics for commit types, scopes, and notes. The convention has influenced tooling, repository maintenance, and release workflows in projects across corporate, open-source, and academic settings.

Overview

The specification was created to make commit history more consistent and parsable for tools used by projects such as Linux kernel, GitHub, GitLab, Apache Software Foundation, and Mozilla Foundation. It provides a concise grammar that integrates with ecosystems involving Semantic Versioning, Continuous Integration platforms like Travis CI, CircleCI, Jenkins, and package registries such as npm, RubyGems, Maven Central, and PyPI. Influential users include organizations like Google, Microsoft, Facebook, Red Hat, and Canonical that apply standardized commit formats to automate changelog generation and release notes for projects like Kubernetes, React (web framework), Rust (programming language), and TensorFlow. The pattern connects to release management practices used in enterprises including Amazon (company), Spotify, Netflix, and Airbnb.

Specification

The convention defines a commit header with a type, optional scope, and short description, followed by an optional body and footer. Types are drawn from concepts common to projects led by institutions such as Linux Foundation, Eclipse Foundation, OpenStack, and W3C. The header syntax is intended to be machine-parseable by tools employed by vendors like Atlassian, JetBrains, SAP SE, and Oracle Corporation. The specification supports markers for breaking changes and metadata trailers used by changelog tools in ecosystems overseen by npm, Inc. and language foundations including Python Software Foundation, Ruby Association, and Apache Software Foundation. Implementations often reference standards like ISO 8601 for timestamps and interoperate with dependency tools such as Dependabot and Snyk.

Types and Scopes

Common types include change categories that mirror roles in projects hosted on platforms like GitHub, GitLab, Bitbucket, and SourceForge and used in projects by Canonical, Debian, Fedora Project, and OpenBSD. Typical types are analogous to labels used in workflows at Mozilla Foundation and Microsoft: fixes for bugs, features for enhancements, docs for documentation, refactor for code restructuring, test for test-related changes, chore for maintenance, and perf for performance. Scopes are project-specific tokens, often matching modules or packages named in ecosystems such as npm, Maven, Cargo (package manager), or CPAN, and are similar to component annotations used by Apache Software Foundation projects like Hadoop and Tomcat. Large organizations including IBM, HP Inc., and Siemens often standardize scope vocabularies to align with product names and teams.

Tooling and Adoption

Adoption is driven by tooling from vendors and communities such as Semantic Release, Commitizen, Conventional Changelog, and integrations provided by GitHub Actions, Azure DevOps, Google Cloud Build, and AWS CodePipeline. Major open-source projects like Angular (web framework), Ember.js, Vue.js, Kubernetes, and Electron (software framework) have adopted or influenced tooling. Enterprise platforms including GitHub Enterprise, GitLab CI/CD, and Bitbucket Server provide automation plugins and templates to enforce conventions used by teams at Facebook, Twitter, LinkedIn, and Stripe. Continuous delivery practices from firms like Pivotal, Heroku, and Docker, Inc. incorporate automated release generation that reads commit metadata.

Examples and Best Practices

Examples of header lines and structured footers are used in changelog generators associated with projects from the Angular, React (web framework), and Vue.js communities, and follow guidance similar to release notes conventions at Google, Apple Inc., and Microsoft. Best practices include using consistent type vocabularies (as practiced by Red Hat and Canonical), scoping commits to modules (as in Kubernetes and Linux kernel development), writing descriptive bodies that reference issue trackers like Jira (software), GitHub Issues, Bugzilla, and Phabricator, and annotating breaking changes for downstream consumers such as Homebrew and Chocolatey. Teams at Netflix and Spotify recommend automation hooks in CI pipelines to validate commit messages, generate semantic version bumps, and produce human-readable changelogs consumed by release managers at Atlassian and SAP SE.

Criticisms and Limitations

Critics, including contributors to projects hosted by GitHub and GitLab, argue that rigid typing and scope requirements can impose administrative overhead on small teams and solo maintainers, mirroring debates seen in communities around Linux kernel and Debian packaging. Some maintainers of projects like jQuery and Bootstrap (front-end framework) prefer minimal commit messages, while enterprise adopters at IBM and Accenture sometimes find standard vocabularies insufficient for complex product lines. Tooling gaps exist for legacy repositories in corporations such as General Electric and Siemens where migration costs are compared to historical transitions like those between Subversion and Git. Security and privacy concerns around automated changelog publishing have been raised by contributors to OpenSSL and Tor (anonymity network) projects.

Category:Software development