Skip to main content
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
AreaScope
SDK codesdk
API backendapi
React Native apprn
Web appweb
Auth systemauth
UI componentsui
Models / schemasmodels
Databasedb
Infrastructureinfra
Build systembuild
Testingtest
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.
Used for:
  • Breaking changes
  • Issue linking
  • Migration notes
  • Deprecations
BREAKING CHANGE: updated payload format
Closes #124

​
Full Examples

feat(sdk): add uploadFile method

fix(api): resolve empty response bug on iOS

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

refactor(auth): extract token refresh logic

feat(api)!: update /login response shape

BREAKING CHANGE: "token" renamed to "accessToken"

docs: update installation instructions for RN SDK

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