🪵Git Conventions

This document outlines the standard conventions for Git commits and branch naming to maintain consistency and clarity across the project.

You can use the following tool to generate commits and branches:

GitHub - Fastiraz/comet: Easy conventional commits maker written in Golang.GitHub

Commits

We follow the Conventional Commits specification for commit messages. This provides a structured format that enables automated changelog generation and semantic versioning.

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

• feat: A new feature for the user

• fix: A bug fix for the user

• docs: Documentation only changes

• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)

• refactor: A code change that neither fixes a bug nor adds a feature

• perf: A code change that improves performance

• test: Adding missing tests or correcting existing tests

• build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)

• ci: Changes to CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)

• chore: Other changes that don't modify src or test files

• revert: Reverts a previous commit

Examples

Simple feature:

feat: add user authentication

Feature with scope:

feat(api): add endpoint for user profile retrieval

Bug fix with body:

fix(auth): resolve token expiration issue

Users were being logged out prematurely due to incorrect
token expiration calculation. This commit fixes the timing
logic to match the expected 24-hour session duration.

Breaking change:

feat(api)!: change response format for user endpoints

BREAKING CHANGE: The user API now returns data in a nested
format under a 'data' key instead of at the root level.
Clients will need to update their response parsing logic.

Chore with scope:

chore(deps): update dependencies to latest versions

Documentation:

docs: update README with installation instructions

Best Practices

• Use the imperative mood in the description ("add" not "added" or "adds")

• Don't capitalize the first letter of the description

• No period (.) at the end of the description

• Keep the description line under 72 characters

• Use the body to explain what and why, not how

• Reference issues and pull requests in the footer when applicable

Branches

Branch names should be descriptive and follow a consistent pattern that indicates the purpose and content of the branch.

Branch Naming Format

<type>/<short-description>

or with ticket reference:

<type>/<ticket-id>-<short-description>

Types

• feature or feat: New feature development

• bugfix or fix: Bug fixes

• hotfix: Urgent fixes for production

• release: Release preparation

• docs: Documentation updates

• refactor: Code refactoring

• test: Adding or updating tests

• chore: Maintenance tasks

Examples

Feature branches:

feature/user-authentication
feat/add-payment-gateway
feature/PROJ-123-user-dashboard

Bug fix branches:

bugfix/login-error
fix/memory-leak-in-worker
bugfix/PROJ-456-cart-calculation

Hotfix branches:

hotfix/critical-security-patch
hotfix/PROJ-789-production-crash

Documentation branches:

docs/api-documentation
docs/update-contributing-guide

Refactoring branches:

refactor/database-layer
refactor/simplify-auth-logic

Release branches:

release/v1.2.0
release/2024-q1

Best Practices

• Use lowercase letters

• Use hyphens (-) to separate words, not underscores or spaces

• Keep branch names concise but descriptive

• Include ticket/issue numbers when applicable

• Delete branches after they are merged

• Avoid using only ticket numbers without description

Protected Branches

The following branches typically have special protection rules:

• main or master: Production-ready code

• develop: Integration branch for features

• release/*: Release candidate branches

These branches often require pull request reviews and passing CI checks before merging.