> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handauncle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Commit Message Guide

> Conventional commit standards for HandaUncle repositories

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

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)]
```

<CodeGroup>
  ```bash Example theme={null}
  feat(auth)!: update OTP verification method

  BREAKING CHANGE: removed verifyOtpOld(), use verifyOtp() instead.
  ```
</CodeGroup>

***

## 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.

<CodeGroup>
  ```bash Examples theme={null}
  feat: add user profile endpoint
  feat(ui): add onboarding carousel
  feat(sdk): add initClient helper
  ```
</CodeGroup>

<Note>Triggers **minor version bump** (`1.2.0 → 1.3.0`)</Note>

***

### 🐞 fix — Bug Fix

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

<CodeGroup>
  ```bash Examples theme={null}
  fix: handle undefined token in RN SDK
  fix(api): correct response type for getUser
  fix(ui): prevent crash on home screen load
  ```
</CodeGroup>

<Note>Triggers **patch version bump** (`1.3.1 → 1.3.2`)</Note>

***

### 🔧 chore — Maintenance Tasks

Used for changes that **do not affect functionality**.

<CodeGroup>
  ```bash Examples theme={null}
  chore: regenerate SDK from updated schema
  chore: update dependencies
  chore: clean unused files
  ```
</CodeGroup>

<Info>Does **not** affect versioning</Info>

***

### 🔁 refactor — Internal Code Improvements

Used when changing code structure **without altering behavior**.

<CodeGroup>
  ```bash Examples theme={null}
  refactor(sdk): reorganize api client utilities
  refactor(auth): simplify token refresh flow
  ```
</CodeGroup>

<Info>Does **not** bump version</Info>

***

### 📚 docs — Documentation Only

Used for changes to documentation, comments, or examples.

<CodeGroup>
  ```bash Examples theme={null}
  docs: update README with installation steps
  docs(api): add usage examples for createUser
  ```
</CodeGroup>

***

### 🎨 style — Code Style Changes

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

<CodeGroup>
  ```bash Examples theme={null}
  style: apply prettier formatting across repo
  style: fix typos in variable names
  ```
</CodeGroup>

***

### 🧪 test — Adding or Modifying Tests

Used when creating or fixing tests.

<CodeGroup>
  ```bash Examples theme={null}
  test: add tests for login flow
  test(api): fix failing mock server tests
  ```
</CodeGroup>

***

### ⚙️ build — Build System Changes

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

<CodeGroup>
  ```bash Examples theme={null}
  build: update tsconfig to target ES2021
  build(rn): fix metro resolver for new SDK
  ```
</CodeGroup>

***

### 🛠️ ci — Continuous Integration

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

<CodeGroup>
  ```bash Examples theme={null}
  ci: add auto-publish workflow for SDK
  ci: fix node version in build pipeline
  ```
</CodeGroup>

***

### 🚀 perf — Performance Improvements

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

<CodeGroup>
  ```bash Examples theme={null}
  perf: reduce RN SDK bundle size
  perf(api): improve search query efficiency
  ```
</CodeGroup>

***

### 🔒 security — Security Fixes

Used when correcting vulnerabilities or implementing secure patterns.

<CodeGroup>
  ```bash Examples theme={null}
  security: sanitize input for auth routes
  security(sdk): encrypt stored auth token
  ```
</CodeGroup>

***

### ↩️ revert — Reverting a Commit

Automatically created by Git when rolling back a previous change.

<CodeGroup>
  ```bash Example theme={null}
  revert: revert feature causing crash on startup
  ```
</CodeGroup>

***

## 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`   |

<CodeGroup>
  ```bash Examples theme={null}
  feat(api): add /users/search endpoint
  fix(auth): resolve token expiry bug
  chore(sdk): regenerate types for v1.4.0
  ```
</CodeGroup>

***

## Breaking Changes

<Warning>
  Breaking changes must be indicated clearly by **adding `!`** after the type or scope.
</Warning>

Format options:

```
feat!: message
feat(api)!: message
```

Additionally, the commit *must* contain a footer:

```
BREAKING CHANGE: <explanation>
```

<CodeGroup>
  ```bash Example theme={null}
  feat(api)!: change login response format

  BREAKING CHANGE: removed "token" field, replaced with "accessToken".
  ```
</CodeGroup>

<Note>Triggers a **major version bump** (`1.3.2 → 2.0.0`)</Note>

***

## Commit Body (Optional)

Used when you need to provide more context.

<CodeGroup>
  ```bash Example theme={null}
  feat(sdk): add new registerUser method

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

***

## Commit Footer (Optional)

Used for:

* Breaking changes
* Issue linking
* Migration notes
* Deprecations

<CodeGroup>
  ```bash Example theme={null}
  BREAKING CHANGE: updated payload format
  Closes #124
  ```
</CodeGroup>

***

## Full Examples

<AccordionGroup>
  <Accordion title="New feature">
    ```bash theme={null}
    feat(sdk): add uploadFile method
    ```
  </Accordion>

  <Accordion title="Bug fix">
    ```bash theme={null}
    fix(api): resolve empty response bug on iOS
    ```
  </Accordion>

  <Accordion title="Regenerating SDK">
    ```bash theme={null}
    chore(sdk): regenerate types from openapi v1.6.0
    ```
  </Accordion>

  <Accordion title="Refactor">
    ```bash theme={null}
    refactor(auth): extract token refresh logic
    ```
  </Accordion>

  <Accordion title="Breaking change">
    ```bash theme={null}
    feat(api)!: update /login response shape

    BREAKING CHANGE: "token" renamed to "accessToken"
    ```
  </Accordion>

  <Accordion title="Documentation">
    ```bash theme={null}
    docs: update installation instructions for RN SDK
    ```
  </Accordion>

  <Accordion title="Tests">
    ```bash theme={null}
    test(api): add unit tests for user search
    ```
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep Subject Short" icon="text-size">
    Subject line should be **under 72 characters**
  </Card>

  <Card title="Use Imperative Tone" icon="terminal">
    Use "add", "fix" — not "adding", "fixed"
  </Card>

  <Card title="Include Scopes" icon="bullseye">
    Add scopes whenever possible for clarity
  </Card>

  <Card title="Single Purpose" icon="list-check">
    Never mix unrelated changes in one commit
  </Card>
</CardGroup>

***

## Commit Template

<CodeGroup>
  ```bash Template theme={null}
  <type>(<scope>): <short, imperative description>

  [optional longer message explaining what changed and why]

  [optional BREAKING CHANGE: <description>]
  ```
</CodeGroup>

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

  ```bash theme={null}
  git config --global commit.template ~/.gitmessage
  ```
</Tip>