Commit Like a Pro: A Beginner’s Guide to Conventional Commits

Are your commit messages a chaotic mess of vague descriptions like “stuff fixed” or “update”? If so, you’re not alone. Many developers struggle to maintain consistency in commit history. But there’s a solution—Conventional Commits.

What are Conventional Commits, and why should you use them? Conventional Commits is a standardized approach to writing commit messages, ensuring clarity, consistency, and better communication in your project’s history. In this guide, we’ll dive deep into what Conventional Commits are, how to use them, and the best practices for enforcing them in your workflow. Plus, we’ll explore how this system can help streamline your process with tools like Jira and semantic release automation.

What Are Conventional Commits?

Conventional Commits is a specification for writing commit messages that follow a structured format, making it easier for teams to understand the intent behind each change. The basic structure is:

<type>[optional scope]: <description>

Here’s a breakdown of the basic types:

• feat: Adds a new feature (e.g., feat: add user authentication via OAuth)
• fix: Fixes a bug (e.g., fix: resolve crashing issue on login page)
• docs: Updates documentation (e.g., docs: add API usage examples)
• chore: Handles non-feature work like maintenance tasks (e.g., chore: update Node.js version)

This system helps eliminate confusion and promotes better collaboration by keeping your commit history clear and consistent.

When to Use “chore” in Conventional Commits

The term “chore” in Conventional Commits is reserved for tasks that don’t directly impact the functionality of your application but are important for maintaining a clean, functional codebase. These tasks often include:

• Dependency updates (e.g., chore: update dependencies)
• Configuration changes (e.g., chore: refactor CI pipeline)
• Non-functional code changes (e.g., chore: optimize build process)

By marking these changes as chore, you ensure they’re clearly distinguished from feature updates or bug fixes in your commit history.

How to Use Conventional Commits in Your Workflow

Using Conventional Commits is simple and follows a straightforward structure. Here’s how to craft your commit messages:

1. The Header

The header is essential and consists of:

• Type (feat, fix, docs, chore)
• Optional Scope (defines the area affected, e.g., feat(auth): or fix(ui):)
• Description (concise summary of the change)

Example:

feat(auth): add login functionality
fix(ui): resolve button alignment issue in Safari

2. The Body (Optional, but Recommended)

The body of your commit message provides context for your change. It’s useful when you need to explain the “why” behind a change.

Example:

fix(auth): correct token validation logic

The token validation was failing due to a mismatch in timezones. 
This fix ensures that UTC is used for all comparisons, resolving the issue.

3. The Footer (Optional, but Helpful)

Use the footer for breaking changes or issue references.

Example:

BREAKING CHANGE: The `authToken` parameter is now required in all API requests.
Refs: #123

Why Should You Adopt Conventional Commits?

There are several compelling reasons to implement Conventional Commits in your development workflow:

1. Improved Clarity

Each commit message clearly conveys the purpose of the change. No more vague, confusing commit descriptions.

2. Automated Changelog Generation

Tools like semantic-release can automatically generate changelogs based on your commit history. When combined with Conventional Commits, this automation helps maintain an up-to-date changelog with minimal effort.

3. Seamless Integration with Jira

Linking commits to Jira tickets is straightforward with Conventional Commits. You can easily reference Jira issues in your commit messages (e.g., fix(auth): resolve token mismatch issue #456), improving traceability.

4. Enforcing Consistency

By standardizing commit messages, you ensure consistency across your team. Tools like commitlint help enforce the rules, making sure everyone follows the same conventions.

5. Improved Debugging

With clear, consistent commit messages, debugging becomes easier. You can quickly identify when a bug was introduced or which commit caused a problem.

Conventional Commits vs. Semantic Commits

Although similar in purpose, Conventional Commits and Semantic Versioning (SemVer) are not exactly the same. Conventional Commits provide a structured approach to writing commit messages, while Semantic Versioning is used for versioning your software releases. However, the two are highly complementary:

• Conventional Commits dictate the structure of commit messages.
• Semantic Versioning (SemVer) determines how to version your releases based on commit types (e.g., feat changes trigger a minor version bump, fix changes trigger a patch version bump).

When used together, they form a powerful combination that simplifies version management and changelog generation.

How to Enforce Conventional Commits

To ensure your team follows the Conventional Commits standard, consider using the following tools:

1. Commitlint: This tool enforces commit message formatting rules. It ensures that your team follows the agreed-upon commit style.
2. Husky: This tool helps set up pre-commit hooks, ensuring commit messages are checked before they are committed.
3. Semantic Release: This tool automates the release process, including versioning, changelog generation, and publishing, all based on Conventional Commits.

Practical Examples of Conventional Commits

Here are a few examples to get you started:

• Adding a new feature: feat(api): add support for GraphQL endpoints
• Fixing a bug: fix(ui): resolve button alignment issue in Safari
• Updating documentation: docs: update FAQ section with new troubleshooting tips
• Maintenance task (chore): chore(deps): update dependencies to latest versions

If you want to learn how to write effective GitHub issues, check out our post on 7 Secrets to Writing GitHub Issues That Get Bugs Fixed Fast.

The Bigger Picture: Why Conventional Commits Matter

Adopting Conventional Commits goes beyond simply improving commit messages—it’s a mindset shift. Here’s why it matters:

• Automation: Tools like semantic-release can automatically handle versioning, changelog generation, and more.
• Collaboration: Clear commit messages reduce confusion and improve team communication.
• Long-Term Benefits: A well-documented commit history makes it easier to onboard new developers and revisit projects.

Your Next Steps with Conventional Commits

Now that you’re familiar with the basics, it’s time to implement Conventional Commits in your workflow:

• Start writing commit messages using the feat, fix, docs, and chore types.
• Use the <type>[optional scope]: <description> format for commit headers.
• Include meaningful commit bodies and footers.
• Reference Jira tickets in your commits using #issue-number or Fixes #issue-number.
• Use tools like commitlint to enforce commit message standards.

With Conventional Commits, you’ll keep your codebase organized, automate key processes, and ensure everyone on your team is on the same page. Ready to commit to better practices? Start now, and watch your development workflow transform.

Bonus Tips: Mastering Commit Message References

• Linking Issues: Adding #issue-number in your commit message links the commit to that issue for easy reference.
  Example: fix(auth): resolve token mismatch issue #456
• Automatically Closing Issues: Using keywords like Fixes #issue-number in your commit message not only references the issue but also automatically closes it when the commit is merged.
  Example: fix(auth): resolve token mismatch issue Fixes #456

If you want to learn how to write effective GitHub issues, check out our post on 7 Secrets to Writing GitHub Issues That Get Bugs Fixed Fast.

Please leave this field empty

Oh hi there 👋
It’s nice to meet you.

Sign up to receive awesome content in your inbox.

We don’t spam! Read our privacy policy for more info.

Check your inbox or spam folder to confirm your subscription.