Wiedii — Política de Commits

Todos los commits deben seguir el formato Conventional Commits con emoji obligatorio:

<type>(<scope>): <emoji> <description>

[optional body]

[optional footer(s)]

El emoji va entre los dos puntos y la descripción. Lo inserta automáticamente el wizard czg cuando useEmoji: true está activo. No omitir el emoji aunque se haga el commit manualmente — usar la tabla de referencia de abajo.

Commit inicial

El primer commit de todo repositorio Wiedii es siempre:

git commit -m "chore: initial commit"

Tipo chore — configuración del repositorio, no modifica src ni tests
Sin scope — aplica al repositorio completo
Sin body ni footer
Único commit sin emoji: se hace directamente con git commit -m antes de que czg esté disponible

Cómo hacer un commit

git add .
bun commit     # abre el wizard czg — RECOMENDADO para todos los commits
# o directamente:
bun czg
# Solo para commits simples y obvios (con emoji manual):
git commit -m "chore: 🔨 update .gitignore"

bunx czg es el fallback únicamente cuando czg no está instalado en el proyecto.

Tipos de commit y emojis obligatorios

El emoji es obligatorio en todos los commits excepto chore: initial commit. El wizard bun commit lo inserta automáticamente. Al hacer commit manual con git commit -m, incluir el emoji correspondiente.

Tipo	Emoji	Cuándo usarlo
`feat`	✨	Nueva funcionalidad
`fix`	🐛	Corrección de un bug
`docs`	📝	Solo documentación
`style`	💄	Formato, sin cambio de lógica
`refactor`	♻️	Reestructuración de código, sin fix ni feature
`perf`	⚡️	Mejora de rendimiento
`test`	✅	Tests añadidos o corregidos
`build`	📦	Sistema de build o dependencias externas
`ci`	🎡	Cambios en configuración de CI/CD
`chore`	🔨	Mantenimiento, sin cambios en src ni tests
`revert`	⏪️	Reverter un commit anterior

Referencia obligatoria a tarea Squadlinx

Todo commit debe referenciar el número de tarea de Squadlinx en el footer. Sin esta referencia no hay trazabilidad entre el código y el trabajo planificado.

Formato

<type>(<scope>): <emoji> <description>

closed #<número>

Ejemplo real (tal como lo genera czg):

chore(config): 🔨 update the token for the company's internal wietoo package

closed #441131

El # antes del número es obligatorio — es el formato que produce el wizard.

Cómo lo gestiona el wizard czg

El wizard de bun commit incluye una pantalla de "ISSUES" al final. Seleccionar closed y escribir #<número>:

? Select the ISSUES type (optional): closed
? List any ISSUES: #441131

czg genera automáticamente el footer closed #441131 en el cuerpo del commit.

Para referenciar múltiples tareas en un solo commit, separarlas con coma:

? List any ISSUES by this change. E.g.: #31, #34: #441131, #441132

Resultado: closed #441131, #441132

Commits sin tarea asociada

Solo están exentos de referenciar tarea los commits que aplican a todo el repositorio sin contexto de trabajo planificado:

chore: initial commit — primer commit de un repo nuevo
Commits de Renovate — generados automáticamente con su propio MR
Commits de release: chore(release): 🔨 bump version to 1.2.0

Cualquier otro commit de desarrollo — feature, fix, refactor, docs, ci, test — debe llevar closed #<número>.

Breaking changes

feat(api)!: ✨ change response format for /users endpoint

BREAKING CHANGE: response now returns `data` wrapper object

Reglas de frecuencia

Commits atómicos: cada commit = un cambio lógico y completo
Mínimo: un commit por unidad de trabajo completada (una función, un fix, un test)
No acumular: no guardar todo el trabajo para un único commit al final del día
Todo commit debe compilar: el proyecto debe funcionar en cada punto de la historia
WIP permitido en ramas feature usando el prefijo wip: — pero hacer squash antes del MR

Si no puedes describir el cambio en una sola línea de commit, dividirlo en varios commits.

commitlint.config.mjs (raíz del proyecto)

El archivo usa extensión .mjs para ESM explícito — no poner "type": "module" en package.json raíz ya que rompe los generators de Nx (ver nx-monorepo).

import { defineConfig } from 'cz-git'

export default defineConfig({
  extends: ['@commitlint/config-conventional'],
  rules: {},
  prompt: {
    alias: { fd: 'docs: fix typos' },
    messages: {
      type: 'Select the type of change that you are committing:',
      scope: 'Denote the SCOPE of this change (optional):',
      customScope: 'Denote the SCOPE of this change:',
      subject: 'Write a SHORT, IMPERATIVE tense description of the change:\n',
      body: 'Provide a LONGER description (optional). Use "|" to break new line:\n',
      breaking: 'List any BREAKING CHANGES (optional). Use "|" to break new line:\n',
      footerPrefixSelect: 'Select the ISSUES type (optional):',
      customFooterPrefix: 'Input ISSUES prefix:',
      footer: 'List any ISSUES. E.g.: #31, #34:\n',
      confirmCommit: 'Are you sure you want to proceed with the commit above?',
    },
    types: [
      { value: 'feat',     name: 'feat:     A new feature',                                                 emoji: ':sparkles:' },
      { value: 'fix',      name: 'fix:      A bug fix',                                                     emoji: ':bug:' },
      { value: 'docs',     name: 'docs:     Documentation only changes',                                    emoji: ':memo:' },
      { value: 'style',    name: 'style:    Changes that do not affect the meaning of the code',            emoji: ':lipstick:' },
      { value: 'refactor', name: 'refactor: A code change that neither fixes a bug nor adds a feature',     emoji: ':recycle:' },
      { value: 'perf',     name: 'perf:     A code change that improves performance',                       emoji: ':zap:' },
      { value: 'test',     name: 'test:     Adding missing tests or correcting existing tests',             emoji: ':white_check_mark:' },
      { value: 'build',    name: 'build:    Changes that affect the build system or external dependencies', emoji: ':package:' },
      { value: 'ci',       name: 'ci:       Changes to our CI configuration files and scripts',             emoji: ':ferris_wheel:' },
      { value: 'chore',    name: "chore:    Other changes that don't modify src or test files",             emoji: ':hammer:' },
      { value: 'revert',   name: 'revert:   Reverts a previous commit',                                    emoji: ':rewind:' },
    ],
    useEmoji: true,
    emojiAlign: 'center',
    useAI: false,
    scopes: ['deps', 'config', 'ci', 'hooks', 'tooling', 'release'],
    allowCustomScopes: true,
    allowEmptyScopes: true,
    customScopesAlign: 'bottom',
    customScopesAlias: 'custom',
    emptyScopesAlias: 'empty',
    upperCaseSubject: false,
    markBreakingChangeMode: false,
    allowBreakingChanges: ['feat', 'fix'],
    breaklineNumber: 100,
    breaklineChar: '|',
    skipQuestions: [],
    issuePrefixes: [{ value: 'closed', name: 'closed:   ISSUES has been processed' }],
    customIssuePrefixAlign: 'top',
    emptyIssuePrefixAlias: 'skip',
    customIssuePrefixAlias: 'custom',
    allowCustomIssuePrefix: true,
    allowEmptyIssuePrefix: true,
    confirmColorize: true,
    defaultBody: '',
    defaultIssues: '',
    defaultScope: '',
    defaultSubject: '',
  },
})

Scopes compartidos

Los scopes base aplican a todos los proyectos Wiedii y estarán centralizados en @wiedii/commitlint-config (monorepo Wiedii). Los repos individuales extienden esta lista con sus propios scopes de dominio.

Scope	Cuándo usarlo
`deps`	Actualización de dependencias
`config`	Archivos de configuración del proyecto (mise.toml, .editorconfig, etc.)
`ci`	Configuración de CI/CD pipelines
`hooks`	Git hooks (lefthook.yaml)
`tooling`	Herramientas de desarrollo (mise, bun, lefthook)
`release`	Proceso de release y versioning

Con allowCustomScopes: true activado, el wizard de czg siempre permite escribir un scope libre si el proyecto lo necesita.

Estado actual: hasta que @wiedii/commitlint-config y @wiedii/changelog-config estén publicados en el monorepo, cada repo define sus scopes directamente en commitlint.config.mjs.

Dependencias de desarrollo requeridas

Las versiones deben ser exactas — ver politicas-core.

{
  "devDependencies": {
    "czg": "1.13.1",
    "@commitlint/cli": "21.0.1",
    "@commitlint/config-conventional": "21.0.1",
    "cz-git": "1.13.1"
  }
}

commitizen no se usa en Wiedii — el wizard es czg invocado con bun commit.

Referencias

czg — guía de instalación y uso del wizard
lefthook — el hook commit-msg valida el mensaje con commitlint
wildcat/wiedii-configs — hooks de lefthook compartidos entre todos los repos

Commit inicial​

Cómo hacer un commit​

Tipos de commit y emojis obligatorios​

Referencia obligatoria a tarea Squadlinx​

Formato​

Cómo lo gestiona el wizard czg​

Commits sin tarea asociada​

Breaking changes​

Reglas de frecuencia​

commitlint.config.mjs (raíz del proyecto)​

Scopes compartidos​

Dependencias de desarrollo requeridas​

Referencias​