GIT Commit Message Naming

Introduction

A well-structured commit message is crucial for maintaining a clean and readable project history. The Conventional Commits specification provides a standard format for commit messages, making it easier to generate changelogs, automate versioning, and improve collaboration. This document outlines the naming conventions and structure for Git commit messages.

Commit Message Format

A commit message should follow this format:

type(scope)!: short description

longer commit body (optional)

BREAKING CHANGE: description (optional)

Examples

Commit with a description and a breaking change 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

Commit with ! indicating a breaking change

feat!: send an email to the customer when a product is shipped

Commit with a scope and ! for a breaking change

feat(api)!: send an email to the customer when a product is shipped

Commit with both ! and BREAKING CHANGE footer

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Commit with no body

docs: correct spelling of CHANGELOG

Commit with a scope

feat(lang): add Polish language

Commit with a multi-paragraph 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 the latest request.

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

Reviewed-by: Z
Refs: #123

Specification

The following guidelines apply:

1. Type Prefix: Commits MUST be prefixed with a type (feat, fix, etc.), an OPTIONAL scope, an OPTIONAL !, and a REQUIRED colon followed by a space.
2. Feature Commits: The feat type MUST be used for new features.
3. Bug Fix Commits: The fix type MUST be used for bug fixes.
4. Scope: A scope MAY be provided in parentheses, describing the code section affected.
5. Description: A short summary MUST follow the prefix.
6. Body: A longer commit body MAY be included, starting one blank line after the description.
7. Footers: Footers MAY be included one blank line after the body, using key-value pairs.
8. Breaking Changes: Breaking changes MUST be indicated with ! in the type or in a BREAKING CHANGE footer.
9. Consistency: Types and commit structures MUST be used consistently.

Benefits of Conventional Commits

• Automated Changelogs: Enables automatic changelog generation.
• Semantic Versioning: Helps determine version bumps (MAJOR, MINOR, PATCH).
• Better Communication: Improves clarity for contributors and maintainers.
• Automated Processes: Can trigger build and release pipelines.

FAQ

How should commits be handled during early development?

Treat commits as if the product is already released to ensure consistency and clarity.

What if a commit conforms to multiple types?

Make multiple commits whenever possible to maintain clarity.

How does this relate to SemVer?

• fix commits correspond to PATCH releases.
• feat commits correspond to MINOR releases.
• BREAKING CHANGE commits correspond to MAJOR releases.

What if I use the wrong commit type?

• Before merging, use git rebase -i to edit the commit history.
• After release, follow your project’s revision process.

Should all contributors follow this standard?

Not necessarily. A lead maintainer can clean up commit messages before merging.

How are revert commits handled?

Use the revert type and reference the commit SHAs being reverted:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Conclusion

Following the Conventional Commits specification ensures a structured commit history, aiding in automation, collaboration, and maintainability. Adopting this practice leads to more organized and meaningful commit logs, benefiting both developers and project maintainers.