Skip to content
Docs
Collaboration
Conventional Commits

Conventional Commits

Ah, Conventional Commits. The salvation of anyone tired of reading messages like “fix stuff” or the classic “small changes” (we all know they are never actually small). This convention adds semantic meaning to commit messages, turning project history from a horror novel into a well-structured documentary.

🏗️ Basic Structure

If you thought writing commits was boring, wait until you see this elegant structure (yes, that is irony, but you will get used to it):

<type>[optional scope]: <description>

[optional body]

[optional footer]

🎯 Main Types (aka “How Not to Lose Your Mind”)

  • feat ✨: new feature (when you finally add the feature the client has been asking for for months)
  • fix 🐛: bug fix (oops!)
  • docs 📚: documentation changes (yes, this matters too)
  • style 💅: formatting changes (because spacing is important)
  • refactor 🔧: code refactoring (when you clean up without anyone noticing)
  • test 🧪: adding or updating tests (better late than never)
  • chore 🧹: build, tooling, configuration, and similar maintenance work (the dirty work nobody wants to do)

🔄 Integration with Jira

Why not let your commits talk directly to Jira? It is like having a personal interpreter:

1
2
3
4

feat(auth): implement OAuth2 login

[PROJ-123] Added Google OAuth2 authentication
# No, this is not magic. It is just organization. 🎩

This allows you to:

  • Track commits related to specific tickets easily
  • Generate changelogs automatically
  • Keep a clear relationship between code and tasks

🛠️ Validation with Cocogitto

Cocogitto is like having a strict but fair professor checking your commits. For macOS (other systems are in the manual; we will not play favorites 😉):

brew install cocogitto

For other operating systems, refer to the official documentation.

Basic Configuration

Create a .cog.toml file at the project root:

1
2
3

from_latest_tag = true
ignore_merge_commits = true
branch_whitelist = ["main", "master"]

🪝 Git Hooks for Validation

Why trust self-checking when you can enforce good habits? Here is how:

Create a .githooks directory at the project root:

1

mkdir .githooks

Create the .githooks/commit-msg file:

1
2
3

#!/bin/sh
MESSAGE=$(cat "$1")
cog verify "$MESSAGE"

Make it executable:

1

chmod +x .githooks/commit-msg

Configure Git to use the new hooks directory:

1

git config core.hooksPath .githooks

This approach allows you to:

  • Version hooks together with the code
  • Share hooks with the team
  • Keep scripts separate from the .git directory

✨ Benefits (or “Why You Should Not Ignore All This”)

Improved DevEx 🚀:

  • Easier history search
  • Automatic changelog generation
  • Automatic semantic versioning

Compliance ✅:

  • Shared standard in the team
  • Automatic validation
  • Integration with CI/CD tools

Traceability 🔍:

  • Direct correlation with tickets
  • Clear and structured project history
  • Easier review process

💡 Best Practices (aka “Golden Rules”)

  1. Brevity is the soul of commits (keep them under 50 characters, not your life story)
  2. Use the present imperative (as if you were giving orders to the code)
  3. Ticket references are positive karma
  4. The commit body is like a diary, but professional
Last updated on
Repository docs