DOCSEARCHbyAlgolia
Submit Docs

Conventional Commits Specification

repository·master·Indexed 27 days ago

https://github.com/conventional-commits/conventionalcommits.org

Official documentation for the Conventional Commits specification, providing a lightweight convention on top of commit messages to enable automated versioning and changelog generation. Includes guidelines on commit structure (type, scope, description, body, and footer), SemVer mappings for fix, feat, and BREAKING CHANGE, and best practices for commit writing. Also contains details for the hugo-conventional-commits-theme used for the official website.

Tokens
29.4K
Snippets
90
Records
189
Agent score
88%

What's inside Conventional Commits

  1. Understand the Conventional Commits structure

    master

    Conventional Commits follow a specific structure to create a clear commit history and enable automation (like SemVer and CHANGELOG generation). A commit message must follow this pattern:

    <type>[optional scope]: <description>

[optional body]

[optional footer]

    Key components:

    • type: A noun describing the change (e.g., feat, fix).
    • scope (optional): A noun in parentheses describing the affected part of the codebase (e.g., feat(parser):).
    • description: A short summary of the change, following a colon and a space.
    • body (optional): Detailed information about the change, separated from the description by a blank line.
    • footer (optional): Metadata like issue references or breaking change notes, separated from the body by a blank line.

  3. Benefits of using Conventional Commits

    master

    Implementing the Conventional Commits specification allows for several automated and manual workflow improvements:

    • Automated CHANGELOG generation: Automatically create release notes based on commit history.
    • Automated Semantic Versioning: Determine the next version bump (major, minor, or patch) based on the commit types.
    • Clear Communication: Communicate the nature of changes clearly to teammates, the public, and other stakeholders.
    • CI/CD Integration: Trigger specific build and publish processes based on commit metadata.
    • Improved Contribution: Make it easier for contributors to explore a structured and predictable commit history.

  4. Explore Tooling for Conventional Commits

    master

    The Conventional Commits specification is supported by a wide ecosystem of tools across various programming languages and platforms. These tools help with parsing, validating, linting, and automating versioning and changelog generation based on commit messages.

    Key categories of tooling include:

    • Linters & Validators: Tools like commitlint, gitlint, cocogitto, and EasyBuild.CommitLinter to ensure commit messages adhere to the specification.
    • Changelog Generators: Tools like git-cliff, chglog, standard-version, and change that transform git history into formatted changelogs.
    • Release Automation: Tools like semantic-release, python-semantic-release, and sv4git that automate version bumping, tagging, and publishing.
    • IDE Support: Extensions for VSCode and JetBrains IDEs to provide templates and inspections for commit messages.
    • Language-Specific Libraries: Support for Go, PHP, Python, Java, .NET, and Node.js.

  7. Indicate a breaking change in a commit message

    master

    To signal a breaking change, you MUST include the uppercase text BREAKING CHANGE: followed by a space at the very beginning of the optional body or footer section. A description of the change must follow the colon.

    feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

  8. Include a BREAKING CHANGE in a commit

    master

    To signal a breaking change that requires a MAJOR version bump, you MUST include the text BREAKING CHANGE: (followed by a space) at the very beginning of either the optional body or the footer. This must be followed by a description of what changed in the code that breaks backward compatibility.

    Example:

    feat: update configuration loading

BREAKING CHANGE: environment variables now take precedence over configuration files.
    BREAKING CHANGE: zmienne środowiskowe mają teraz większy priorytet niż pliki konfiuguracyjne.

  9. Signal a BREAKING CHANGE

    master

    There are two ways to indicate a breaking change in a commit message:

    1. Using an exclamation mark (!): Place a ! immediately after the type or scope (e.g., refactor!: description). If you use this method, the BREAKING CHANGE: footer is optional, and the commit description itself serves as the breaking change description.
    2. Using a footer: Include BREAKING CHANGE: (or BREAKING-CHANGE) in the footer section, followed by a colon and a description (e.g., BREAKING CHANGE: description).

    Both methods trigger a MAJOR version bump in SemVer-compatible tools.

    ### Example with `!`:

    refactor!: drop support for Node 6

    
### Example with footer:

    feat: allow provided config object to extend other configs

    BREAKING CHANGE: extends key in config file is now used for extending other config files

  10. Add context and body to commit messages

    master

    To provide more detail in your commits:

    • Context: Add a noun in parentheses after the type to describe the part of the code affected (e.g., feat(parser): add ability to parse arrays).
    • Body: Provide additional context for the change by adding a body. The body must be separated from the description by one blank line.
    • Footers: Use footers for metadata (like Refs: #123 or Reviewed-by: Z). Footers must follow the git trailer format. Use a hyphen (-) instead of a space in footer tokens (e.g., Acked-by: instead of Acked by:).
    ### Commit with context
feat(lang): add polish language

### Commit with body and multiple footers
fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

  11. Use Scope and Breaking Change Indicators

    master

    To provide more context or highlight critical changes, use the following syntax:

    • Scope: A noun enclosed in parentheses immediately following the type to describe the part of the code affected. Example: feat(parser): add ability to parse arrays.
    • Breaking Change Indicator (!): An exclamation mark can be added after the type/scope and before the colon to draw attention to a breaking change. If ! is used, a BREAKING CHANGE: description must also be included in the body or footer.
    feat(lang): add polish language

chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

  12. Follow the Conventional Commit specification rules

    master

    To adhere to the specification, follow these rules:

    1. Type Prefix: Every commit must use a type field prefix consisting of a noun like feat or fix, followed by a colon and a space.
    2. New Features: Use feat when implementing a new feature.
    3. Bug Fixes: Use fix when fixing a bug.
    4. Scope: An optional scope can be provided in parentheses after the type (e.g., fix(parser):).
    5. Description: A description must immediately follow the type or scope. It should be a short summary of the pull request.
    6. Body: An optional body can be written after a blank line following the description.
    7. Footer: An optional footer can be written after a blank line following the body. Footers should contain metadata like fixed issues (e.g., fixes #13).
    8. Breaking Changes: A breaking change must be indicated in the body or footer using the uppercase text BREAKING CHANGE: followed by a colon and a space, then a description of the API change.