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

# Git Commit Convention

> Consistent commit messages improve history readability and enable automated tooling (e.g., changelog generation). This project **mandates** adherence to the **Conventional Commits** specification ([https://www.conventionalcommits.org/](https://www.conventionalcommits.org/)).

## Mandatory Format

```
<type>(<scope>): <subject>
<BLANK LINE>
[optional body]
<BLANK LINE>
[optional footer(s)]
```

## Rules & Components

1. **Type:** Defines the *kind* of change. Must be one of the allowed types listed below.
2. **Scope:** Must be provided and enclosed in parentheses. Indicates the logical part of the codebase affected (e.g., `core`, `services`, `radicacion`, `asignacion`, `auth`, `ds-tw`). Choose the most relevant scope.
3. **Subject:** Concise description (\< 50 chars recommended) of the change in lowercase imperative mood (e.g., "add," "fix," "update"). Must not end with a period.
4. **Body (Optional):** Use to provide context, motivation, or details. Separate from subject with a blank line. Wrap lines at 72 characters.
5. **Footer (Optional):** Use for referencing issue IDs (e.g., `Refs ADO-123`, `Fixes #456`) and **mandatory** for `BREAKING CHANGE:` notifications. Separate from body with a blank line.

## Standard Commit Types (with Examples)

* ✨ `feat(<scope>): <description>`
  * **Purpose:** Introduces a new feature or functionality visible to the end-user.
  * **Example:** `feat(radicacion): add drag-and-drop file upload for expedientes`
* 🐛 `fix(<scope>): <description>`
  * **Purpose:** Corrects a bug in the codebase.
  * **Example:** `fix(services): handle null priority in DefaultAsignacionService`
* 📚 `docs(<scope>): <description>`
  * **Purpose:** Changes related solely to documentation (READMEs, guides, code comments).
  * **Example:** `docs(core): update UserService interface method descriptions`
* 🎨 `style(<scope>): <description>`
  * **Purpose:** Code style adjustments (formatting, whitespace, semicolons) without changing logic. Applicable also to Design System usage or config (`ds-tw` scope if modifying DS itself).
  * **Example:** `style(radicacion): apply consistent padding using ds-tw vars`
* ♻️ `refactor(<scope>): <description>`
  * **Purpose:** Restructuring existing code without changing its external behavior (improving readability, extracting methods, etc.).
  * **Example:** `refactor(services): extract common validation logic in UserService implementations`
* ⚡️ `perf(<scope>): <description>`
  * **Purpose:** Code changes aimed specifically at improving performance.
  * **Example:** `perf(web): optimize image loading on dashboard page using next/image`
* 🧪 `test(<scope>): <description>`
  * **Purpose:** Adding new tests or modifying existing ones. No production code changes.
  * **Example:** `test(services): add unit tests for DefaultUserService`
* 🏗️ `build(<scope>): <description>`
  * **Purpose:** Changes impacting the build process, dependencies, or project setup (e.g., pnpm, Next.js config, Docker, Turborepo config).
  * **Example:** `build(deps): upgrade xstate to v5`
* ⚙️ `ci(<scope>): <description>`
  * **Purpose:** Modifications to Continuous Integration/Continuous Deployment configuration or scripts (e.g., GitHub Actions, Azure Pipelines).
  * **Example:** `ci: add type checking stage to github actions workflow`
* 🧹 `chore(<scope>): <description>`
  * **Purpose:** Routine tasks or maintenance that don't fit other types (e.g., updating `.gitignore`, tooling config, release tasks).
  * **Example:** `chore: update eslint configuration rules for new plugin`
* ⏪️ `revert(<scope>): <description>`
  * **Purpose:** Reverts a previous commit. The subject should clearly indicate what is being reverted.
  * **Example:** `revert: feat(radicacion): remove experimental search feature`
  * *The body MUST explain the reason for the revert and reference the original commit hash.*

**Scope Examples:** `(core)`, `(hooks)`, `(config)`, `(services)`, `(machines)`, `(validation)`, `(radicacion)`, `(asignacion)`, `(auth)`, `(deps)`, `(ci)`, `(docs)`, `(release)`, `(ds-tw)`. Select the most specific and relevant scope.

## BREAKING CHANGES

* Any commit introducing a backward-incompatible change **must** include a `BREAKING CHANGE:` footer section.
* This section must start with the exact words `BREAKING CHANGE:`, followed by a detailed description of the change, the justification, and any necessary migration instructions.

```
refactor(core): change user ID from number to UUID

BREAKING CHANGE: User.id field type changed from number to string (UUID).
Reason: Need for globally unique identifiers across federated systems.
Migration: Database schema update required (run migration script V3). API consumers must adapt to expect string IDs instead of numbers for all user endpoints. Refer to migration guide linked in ADO-789 for details.
```

<Error>
  **Enforcement:** Non-compliant commit messages may cause CI/CD pipeline failures or Pull Request rejection. Strict adherence to this standard is mandatory for all contributors.
</Error>

```
```