Skip to content

Latest commit

 

History

History
62 lines (39 loc) · 4.23 KB

commit-standards.md

File metadata and controls

62 lines (39 loc) · 4.23 KB
Raw

Commit standards refer to a set of guidelines for writing meaningful and structured commit messages in a version control system like Git. By following these standards, teams can make their code history more understandable and maintainable, helping developers track changes and reason about the evolution of a project. These standards often define a specific structure for commit messages, including rules for prefixes, types, and formatting. The goal is to improve readability, enable automated tooling, and support workflows like semantic versioning.

Conventional Commits

The Conventional Commits standard is one of the most widely adopted guidelines for structuring commit messages. It specifies a simple, human-readable format designed for compatibility with semantic versioning. The format consists of a type, an optional scope, and a description:

<type>(<scope>): <description>
  • Type: Describes the category of the change, such as feat for new features, fix for bug fixes, docs for documentation changes, etc.
  • Scope: (Optional) A component or module the change relates to, such as auth, api, or ui.
  • Description: A brief summary of the change.

An example of a conventional commit message:

feat(auth): add OAuth 2.0 authentication flow

The key benefits of using Conventional Commits are:

  1. Clarity: Commit messages are consistent and clear across the team.
  2. Automation: Tools can automatically generate changelogs, calculate release numbers, and integrate into CI/CD workflows.
  3. Semantic Versioning: Commits can be parsed to determine when a new release is a patch, minor, or major version based on the commit types.

Other Commit Standards and Newer Alternatives

  1. Gitmoji: Gitmoji uses emojis to represent different types of changes (like 🐛 for bugs and ✨ for features). This standard is especially popular among teams who appreciate visual cues for different types of commits. It adds some personality and can help developers identify changes more quickly. Gitmoji can be used with Conventional Commits for both emoji and structured commit messages.

    Example:

    ✨ feat: add new login flow with multi-factor authentication

  2. Semantic Commit Messages: Similar to Conventional Commits, but sometimes with a slightly different syntax. This can include prefixes for commit messages but might focus more on natural language, allowing some flexibility.

  3. Karma Commit Message Style: This format originated in AngularJS and served as the basis for Conventional Commits. It follows a similar structure (type, scope, description) and is compatible with semantic versioning.

  4. Commitizen: A CLI tool that guides developers through creating standardized commit messages by asking questions about the type, scope, and description. Commitizen supports Conventional Commits out of the box and can be customized for other standards.

  5. Husky and Lint-staged: These tools work together to enforce commit message standards by integrating linting and formatting checks into Git hooks. They don’t define a commit standard themselves but help enforce standards in the codebase.

  6. Emojicommit: Another standard that primarily uses emojis but with a structure more focused on descriptions and changes. It's more expressive and flexible than Gitmoji, without the strict adherence to Conventional Commits syntax.

Using Emoji in Conventional Commits

Yes, you can add emojis to Conventional Commits if your team prefers this style! Many teams combine emojis with Conventional Commits syntax to make commit history visually distinct and enjoyable to read. For example:

✨ feat(auth): add OAuth 2.0 authentication flow
🐛 fix(ui): correct button alignment in header

Choosing the Right Standard

Which commit standard is best for you depends on:

  • Project requirements: Teams needing strict semantic versioning often prefer Conventional Commits.
  • Team preferences: If your team values visual communication, a combination of Conventional Commits with Gitmoji can be effective.
  • Tooling support: If you’re using tools for automation and changelog generation, Conventional Commits are widely supported.