A Practical Conventional Commits Cheat Sheet

Conventional Commits provide a standardized way to structure commit messages, making it easier for teams to understand the history of changes in a project. This cheat sheet outlines the key types of commits and their practical applications, helping developers maintain clear and concise commit messages.

What are Conventional Commits?

Conventional Commits follow a specific format that categorizes commits based on their purpose. This system enhances readability and assists automation tools like semantic-release in generating changelogs and versioning.

Basic Format

The basic structure of a Conventional Commit message is:

<type>[optional scope]: <description>

• type: The type of change (e.g., feat, fix).
• scope: An optional section indicating the affected area of the codebase.
• description: A short summary of the change.

Types of Commits

1. Features: feat

Use feat for new features or enhancements to existing functionality.

git commit -m "feat(auth): add JWT authentication"

2. Fixes: fix

The fix type is for bug fixes that resolve issues in the codebase.

git commit -m "fix(api): correct response status code"

3. Refactoring: refactor

Use refactor for code changes that neither fix a bug nor add a feature. This includes improving code structure without altering functionality.

git commit -m "refactor(user): simplify user validation logic"

4. Documentation: docs

The docs type is for changes that affect the documentation, such as README files or other documentation resources.

git commit -m "docs(README): update installation instructions"

5. Styles: style

Use style for changes that do not affect the meaning of the code (white-space, formatting, etc.).

git commit -m "style: format code according to ESLint rules"

6. Tests: test

The test type is for adding or modifying tests without affecting the application code.

git commit -m "test(auth): add unit tests for login functionality"

7. Chores: chore

Use chore for routine tasks and maintenance that don't fit into other categories.

git commit -m "chore: update dependencies"

8. Performance: perf

The perf type is for changes that improve performance.

git commit -m "perf(api): optimize database queries"

9. Continuous Integration: ci

Use ci for changes related to the CI configuration files and scripts.

git commit -m "ci: update Travis CI configuration"

10. Build: build

The build type is for changes that affect the build system or external dependencies.

git commit -m "build: upgrade webpack to v5"

11. Reverts: revert

Use revert to indicate that a previous commit is being undone.

git commit -m "revert: undo previous commit on auth feature"

Benefits of Using Semantic Release

By adopting Conventional Commits, you enable the use of tools like semantic-release. This automation tool analyzes commit messages to:

• Automatically determine the next version number based on the types of commits.
• Generate a changelog documenting changes since the last release.
• Publish releases to package registries without manual intervention.

The result? A streamlined release process that minimizes human error and enhances team productivity.

Practical Example

Here’s a quick example of how you might use Conventional Commits in your workflow. Let's say you've added a new feature to your project. Your commit message could look like this:

git commit -m "feat(ui): implement dark mode toggle"

When you run semantic-release, it will recognize this message, increment the version automatically, and create a changelog entry that reflects the new feature.

Wrapping Up

Using Conventional Commits can drastically improve the clarity of your commit history and facilitate automated processes. For generating detailed pull request descriptions from your git diffs, check out PullRequestAI. This tool can help bridge the gap between code changes and effective communication in your development team.