Commit Message Guide

This guide MUST be followed for all commits across HandaUncle repositories. Non-compliant commits may be rejected during code review.

This document explains the commit message format used across all repositories. Following this standard ensures:

Clean and searchable commit history
Automatic changelog generation
Semantic versioning (major/minor/patch)
Clear communication across teams
Automated SDK publishing + CI pipelines

Commit Message Format

Every commit follows this structure:

<type>[optional scope][!]: <short description>

[optional body]

[optional footer(s)]

feat(auth)!: update OTP verification method

BREAKING CHANGE: removed verifyOtpOld(), use verifyOtp() instead.

Commit Types (Prefixes)

Below is the complete list of prefixes used in modern engineering teams.

✅ feat — New Feature

Used when adding new capabilities, endpoints, UI elements, models, or SDK methods.

feat: add user profile endpoint
feat(ui): add onboarding carousel
feat(sdk): add initClient helper

Triggers minor version bump (1.2.0 → 1.3.0)

🐞 fix — Bug Fix

Used when fixing incorrect behavior, broken logic, bad types, crashes, or regressions.

fix: handle undefined token in RN SDK
fix(api): correct response type for getUser
fix(ui): prevent crash on home screen load

Triggers patch version bump (1.3.1 → 1.3.2)

🔧 chore — Maintenance Tasks

Used for changes that do not affect functionality.

chore: regenerate SDK from updated schema
chore: update dependencies
chore: clean unused files

Does not affect versioning

🔁 refactor — Internal Code Improvements

Used when changing code structure without altering behavior.

refactor(sdk): reorganize api client utilities
refactor(auth): simplify token refresh flow

Does not bump version

📚 docs — Documentation Only

Used for changes to documentation, comments, or examples.

docs: update README with installation steps
docs(api): add usage examples for createUser

🎨 style — Code Style Changes

Used for formatting, styling, lint fixes, or naming improvements.

style: apply prettier formatting across repo
style: fix typos in variable names

🧪 test — Adding or Modifying Tests

Used when creating or fixing tests.

test: add tests for login flow
test(api): fix failing mock server tests

⚙️ build — Build System Changes

Used for changes in the build pipeline, bundlers, tooling, dependencies, or configuration.

build: update tsconfig to target ES2021
build(rn): fix metro resolver for new SDK

🛠️ ci — Continuous Integration

Used for changes to GitHub Actions, pipelines, scripts, and automation.

ci: add auto-publish workflow for SDK
ci: fix node version in build pipeline

🚀 perf — Performance Improvements

Used when improving performance, reducing latency, or optimizing code.

perf: reduce RN SDK bundle size
perf(api): improve search query efficiency

🔒 security — Security Fixes

Used when correcting vulnerabilities or implementing secure patterns.

security: sanitize input for auth routes
security(sdk): encrypt stored auth token

↩️ revert — Reverting a Commit

Automatically created by Git when rolling back a previous change.

revert: revert feature causing crash on startup

Using Scopes

Scopes clarify where the change happened. Format:

<type>(scope): message

Recommended Scopes

Area	Scope
SDK code	`sdk`
API backend	`api`
React Native app	`rn`
Web app	`web`
Auth system	`auth`
UI components	`ui`
Models / schemas	`models`
Database	`db`
Infrastructure	`infra`
Build system	`build`
Testing	`test`

feat(api): add /users/search endpoint
fix(auth): resolve token expiry bug
chore(sdk): regenerate types for v1.4.0

Breaking Changes

Breaking changes must be indicated clearly by adding ! after the type or scope.

Format options:

feat!: message
feat(api)!: message

Additionally, the commit must contain a footer:

BREAKING CHANGE: <explanation>

feat(api)!: change login response format

BREAKING CHANGE: removed "token" field, replaced with "accessToken".

Triggers a major version bump (1.3.2 → 2.0.0)

Commit Body (Optional)

Used when you need to provide more context.

feat(sdk): add new registerUser method

The backend now exposes POST /v1/auth/register.
This commit includes client implementation + models.

Commit Footer (Optional)

Used for:

Breaking changes
Issue linking
Migration notes
Deprecations

BREAKING CHANGE: updated payload format
Closes #124

Full Examples

New feature

feat(sdk): add uploadFile method

Bug fix

fix(api): resolve empty response bug on iOS

Regenerating SDK

chore(sdk): regenerate types from openapi v1.6.0

Refactor

refactor(auth): extract token refresh logic

Breaking change

feat(api)!: update /login response shape

BREAKING CHANGE: "token" renamed to "accessToken"

Documentation

docs: update installation instructions for RN SDK

Tests

test(api): add unit tests for user search

Best Practices

Keep Subject Short

Subject line should be under 72 characters

Use Imperative Tone

Use “add”, “fix” — not “adding”, “fixed”

Include Scopes

Add scopes whenever possible for clarity

Single Purpose

Never mix unrelated changes in one commit

Commit Template

<type>(<scope>): <short, imperative description>

[optional longer message explaining what changed and why]

[optional BREAKING CHANGE: <description>]

Copy this template and save it as .gitmessage in your home directory, then run:

git config --global commit.template ~/.gitmessage

Overview

Contributing

Codebase

AI Tools

Practices

Commit Message Format

Commit Types (Prefixes)

✅ feat — New Feature

🐞 fix — Bug Fix

🔧 chore — Maintenance Tasks

🔁 refactor — Internal Code Improvements

📚 docs — Documentation Only

🎨 style — Code Style Changes

🧪 test — Adding or Modifying Tests

⚙️ build — Build System Changes

🛠️ ci — Continuous Integration

🚀 perf — Performance Improvements

🔒 security — Security Fixes

↩️ revert — Reverting a Commit

Using Scopes

Recommended Scopes

Breaking Changes

Commit Body (Optional)

Commit Footer (Optional)

Full Examples

Best Practices

Keep Subject Short

Use Imperative Tone

Include Scopes

Single Purpose

Commit Template

​Commit Message Format

​Commit Types (Prefixes)

​✅ feat — New Feature

​🐞 fix — Bug Fix

​🔧 chore — Maintenance Tasks

​🔁 refactor — Internal Code Improvements

​📚 docs — Documentation Only

​🎨 style — Code Style Changes

​🧪 test — Adding or Modifying Tests

​⚙️ build — Build System Changes

​🛠️ ci — Continuous Integration

​🚀 perf — Performance Improvements

​🔒 security — Security Fixes

​↩️ revert — Reverting a Commit

​Using Scopes

​Recommended Scopes

​Breaking Changes

​Commit Body (Optional)

​Commit Footer (Optional)

​Full Examples

​Best Practices

Keep Subject Short

Use Imperative Tone

Include Scopes

Single Purpose

​Commit Template

Commit Message Format

Commit Types (Prefixes)

✅ feat — New Feature

🐞 fix — Bug Fix

🔧 chore — Maintenance Tasks

🔁 refactor — Internal Code Improvements

📚 docs — Documentation Only

🎨 style — Code Style Changes

🧪 test — Adding or Modifying Tests

⚙️ build — Build System Changes

🛠️ ci — Continuous Integration

🚀 perf — Performance Improvements

🔒 security — Security Fixes

↩️ revert — Reverting a Commit

Using Scopes

Recommended Scopes

Breaking Changes

Commit Body (Optional)

Commit Footer (Optional)

Full Examples

Best Practices

Commit Template