Skip to main content

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