Conventional Commit Initiative

Owned by Pavlo Smahin
Last updated: May 18, 2023 by Viacheslav Kolesnyk

Conventional Commits Instruction

What are conventional commits?

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It provides a simple set of rules for creating an explicit commit history, which makes it easier to write automated tools on top of it.

Why should we use conventional commits?

By using conventional commits, we can improve the clarity and readability of our commit messages, which makes it easier for everyone to understand what changes were made and why they were made. This makes it easier to review code and track changes over time. Additionally, conventional commits allow for better automation of release notes, versioning, and changelogs.

How to write conventional commits

To write a conventional commit, use the following format:

<type>([scope]): <description>

[body]

[footer]

Type

The type of the commit message is used to categorize the changes you are making. It should be one of the following:

  • feat: A new feature
  • fix: A bug fix
  • refactor: A code change that neither fixes a bug nor adds a feature
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests
  • ci: Indicates changes related to the Continuous Integration process
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Scope (optional)

The scope of the commit message is used to specify which part of the codebase is being changed. This is optional but highly recommended, as it makes it easier to search for changes in specific parts of the codebase.

Description

The description should be a short summary of the changes being made, written in an imperative mood.

Body (optional)

The body of the commit message should provide a more detailed description of the changes being made. It should be written in the present tense and provide context for the changes being made.

The footer of the commit message can be used to reference issue trackers, provide breaking changes information, and reference other related commits.

Best practices

Here are some best practices to follow when using conventional commits:

  • Use the imperative mood in your commit message, e.g. "Fix bug" instead of "Fixed bug".
  • Keep the scope of the commit message as narrow as possible.
  • Keep the description of the commit message short and to the point.
  • Use the body of the commit message to provide additional context and details.
  • Use the footer of the commit message to reference related issues or commits.
  • Use consistent language and formatting throughout your commit messages.

Examples

Feature:

feat(user-profile): add ability to upload profile picture

Add a new feature to allow users to upload a profile picture from their account page. This feature has been requested by multiple users and will improve the overall user experience.

- Add a new button to the user profile page to upload a picture
- Create a new API endpoint to handle profile picture uploads
- Add validation to ensure that uploaded images are within size limits and in the correct file format

Closes ISSUE-1234

Feature with breaking change:

feat(payment): add new payment gateway

- Add new payment gateway integration
- Remove support for the old payment gateway
- Update payment processing code to work with the new gateway

BREAKING CHANGE: 
Removes support for the old payment gateway. Merchants who were previously using the old gateway will need to update their payment processing code to use the new gateway.

Closes ISSUE-1234

Bug fix:

fix(authentication): handle password reset errors gracefully

Previously, if a user attempted to reset their password but entered an incorrect email address, the application would crash. This commit fixes the issue by handling errors gracefully and displaying an error message to the user.

- Add error handling to the password reset endpoint
- Update the password reset form to display error messages to the user

Closes ISSUE-1234

Documentation:

docs(readme): add instructions for installing dependencies

- Add instructions for installing dependencies using
- Include a list of required dependencies and their versions

Closes ISSUE-1234

Tools