Skip to main content

Conventional Commits

Introduction​

Our team faced challenges with inconsistent git commit messages, leading to a confusing project history. This made it difficult to track changes, understand the project's evolution, and collaborate effectively.

These are some examples of the commit messages that were causing confusion in some of our team's projects:

To overcome this challenge, we should adopt this Conventional Commits specification. This approach brings several benefits:

  1. Automated CHANGELOGs: Clear categorization of commits allows for automated changelog generation, saving time and improving documentation accuracy.

  2. Semantic Versioning: Commit types directly inform version updates, making the process straightforward and logical.

  3. Clear Communication: Structured commit messages enhance clarity for both team members and external stakeholders, facilitating better collaboration.

  4. Efficient Processes: Well-defined commits streamline build and publish processes, improving the software delivery pipeline.

  5. Easier Contribution: A structured commit history makes it simpler for new contributors to understand the project and participate effectively.

Adopted Conventions​

Given our team's size, we focus on key commit types for clarity and efficiency:

  • feat: Introduces a new feature or removes an existing feature.
  • fix: Fixes a bug, making the application function as intended.
  • refactor: Improves code without changing external behavior, including code formatting and removing redundancy.
  • style: Changes that affect the style of the application, such as CSS changes that alter the frontend look without impacting functionality.
  • chore: Routine tasks that don't modify the application code or test files, such as updating dependencies.
  • revert: Reverses a previous commit, useful for quickly addressing issues introduced by recent changes.

Examples​

Here are some examples of how to structure commit messages using our conventions:

  1. feat: Adding a new login feature.

    feat(auth): implement user login functionality

    This commit message signals the addition of a new feature related to user authentication.

  2. fix: Correcting a bug where users could submit a form without filling all required fields.

    fix(form-validation): ensure all fields are filled before submission

    This communicates a bug fix in form validation logic.

  3. refactor: Restructuring the user service to improve code readability without changing its functionality.

    refactor: improve readability and structure

    Indicates an internal code improvement that doesn't affect the service's external behavior.

  4. style: Updating the styling of the login page.

    style(login-page): update CSS for better layout

    This commit specifically targets changes to the look and feel of the login page, such as adjustments to CSS.

  5. chore: Updating project dependencies to their latest versions.

    chore(dependencies): upgrade React to version 17.0.0

    This type of commit is for routine tasks that keep the project up-to-date but don't directly impact the application's functionality.

  6. revert: Undoing a recent commit that introduced a bug in the login functionality.

    revert: revert commit a1b2c3d
    Revert "feat(auth): implement user login functionality"

    This reverts commit a1b2c3d4e5f6g7h8i9j0.

    Used to indicate the reversal of a previous commit, providing a clear trail of what was undone and why.