Wiedii — Política de Commits

🔄 Actualizado 2026-07-06 — el mecanismo cambió de czg/commitlint a wietoo. El formato descrito en esta página (tipos, emojis, footer closed #<id>) sigue siendo el estándar vigente y no cambió. Lo que cambió es cómo se aplica: el asistente y el validador ya no son bun commit (czg) + commitlint, sino el binario nativo wietoo — sin Node, igual en todos los stacks. Guía completa: wietoo-cli. La nota czg queda como referencia histórica.

⚠️ Verificar versiones antes de usar — la versión de wietoo pinneada en mise.toml puede estar desactualizada. Ver wietoo-cli y politicas-core.

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 asistente wietoo commit. 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 wietoo esté instalado (aún no corriste mise run setup)

Cómo hacer un commit

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

Ver wietoo-cli para el detalle de cada pregunta del asistente, con un ejemplo completo.

Commits no-interactivos (agentes de IA / CI)

El asistente wietoo commit es interactivo, así que un agente o un script en CI no puede usarlo — hace el commit con git commit directamente (con su emoji y su footer closed #<id> manuales). Reglas:

• Cuerpo multilínea → -m repetido (forma preferida). Cada -m es un párrafo; no necesita archivo y no hay riesgo de colisión:

  git commit -m "fix(api): 🐛 validate the user id before the query" \
             -m "Evita un panic cuando el id llega vacío desde el handler." \
             -m "closed #441131"

• Nunca heredoc con cat. La regla #12 (preferir CLIs Rust) bloquea cat como comando líder cuando bat está instalado, así que cat <<EOF > msg falla. Y --no-verify también está prohibido.

• Solo si el cuerpo es largo/estructurado → archivo + git commit -F. El archivo debe ser único por proyecto para que dos agentes no se pisen el mismo /tmp/commit_msg.txt. Usar $TMPDIR (en macOS ya es por-usuario) namespaced con el slug plano del proyecto (no partir el slug por guiones — es ambiguo):

  d="${TMPDIR:-/tmp}/wiedii/$(basename "$(git rev-parse --show-toplevel)")"
  mkdir -p "$d"
  # escribir el mensaje en "$d/COMMIT_EDITMSG" (con el editor/Write del agente, no con cat)
  git commit -F "$d/COMMIT_EDITMSG"

  El commit-msg hook (wietoo check-commit-msg) corre igual con -F y con -m: el mensaje se valida siempre.

• El mismo namespacing por proyecto aplica a cualquier otro archivo de cuerpo que escriba un agente — no solo al de git commit -F, sino también a una descripción de MR larga pasada a glab mr create/update --description "$(< "$d/MR_BODY.md")" (escribir la descripción a un archivo también evita el falso positivo de un guardrail cuando la prosa contiene tokens como el nombre de un gestor de paquetes). Escribirlo bajo el mismo "$d/" (${TMPDIR:-/tmp}/wiedii/<slug>/), nunca un /tmp/<nombre> plano que otro agente o proyecto pueda pisar, y borrarlo al terminar.

Tipos de commit y emojis obligatorios

El emoji es obligatorio en todos los commits excepto chore: initial commit. El wizard wietoo 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 wietoo commit):

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 asistente wietoo commit

El asistente incluye una pregunta final de "Issues closed by this change". Escribir el número:

? Issues closed by this change, e.g. #123, #124 (empty to skip): #441131

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

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

? Issues closed by this change, e.g. #123, #124 (empty to skip): #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>.

Atribución de IA (commits y MR hechos con asistencia de IA)

Cuando un commit o un MR se hace con asistencia de IA, debe quedar claro qué herramienta y qué modelo se usó — por transparencia y trazabilidad. No sustituye la autoría ni la responsabilidad del humano que firma el commit/MR.

En el commit — trailer Co-authored-by:

Wiedii usa el trailer Co-authored-by: — el que GitLab reconoce y renderiza, y el default de Claude Code. Convive con closed #<id>:

feat(api): ✨ add rate limiting to the login endpoint

Co-authored-by: Claude Code (claude-sonnet-5) <noreply@anthropic.com>
closed #441131

• Herramienta: una de la lista blanca de IA — Claude Code, Cowork (ver politicas-core). Ninguna otra está autorizada (actualizado 2026-07-15: Codex, Antigravity CLI y Kiro quedaron fuera).
• Modelo: el identificador concreto entre paréntesis cuando se conoce (p. ej. claude-sonnet-5, claude-opus-4-8, gpt-5-codex); si no se conoce el modelo exacto, indicar al menos la herramienta.
• Email: incluir el <email> que exponga la herramienta (Claude Code usa <noreply@anthropic.com>) para que GitLab enlace el co-autor; si la herramienta no expone uno, se puede omitir.
• Claude Code por defecto añade Co-authored-by: Claude <noreply@anthropic.com> (sin el modelo) — complementarlo para que incluya herramienta + modelo según esta convención.
• Agentes (que commitean con git commit -m): añaden el trailer como un -m extra. En wietoo commit se agrega en el cuerpo/footer.
• Si el cambio no usó IA, no se añade el trailer.

Nota: hay debate en la industria sobre usar Co-authored-by para mera asistencia (implica coautoría, y generó backlash cuando VS Code lo activó por defecto en 2026). Wiedii lo adopta por interoperabilidad con GitLab; la autoría y la responsabilidad siguen siendo del humano que firma el commit/MR.

En el Merge Request

La descripción del MR debe llevar la misma atribución (herramienta + modelo) cuando el trabajo se asistió con IA — una línea en la descripción o un campo en la plantilla de MR. Ver git-flow.

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.

Configuración de scopes — wietoo.toml

Los scopes base aplican a todos los proyectos Wiedii. Los repos individuales pueden extender esta lista con sus propios scopes de dominio en un archivo wietoo.toml, opcional, en la raíz del repo:

# wietoo.toml
[commit]
  scopes = ["deps", "config", "ci", "hooks", "tooling", "release"]

Scope base	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

Sin wietoo.toml (o sin [commit].scopes), el asistente sugiere esta misma lista base pero no restringe — cualquier scope, o ninguno, es válido. Con [commit].scopes definido, wietoo check y el hook commit-msg rechazan cualquier commit con un scope fuera de la lista — el mismo rol que cumplía scope-enum en commitlint. Un mantenedor del repo la crea con wietoo init en vez de escribirla a mano. Ver wietoo-cli para el detalle completo, incluyendo ejemplos de commits que pasan y que fallan.

Herramientas requeridas

wietoo no necesita ninguna dependencia de package.json — es un binario nativo instalado vía mise, igual en todos los stacks:

# mise.toml
[tools]
  "go:gitlab.wiedii.co/wiedii-registry/wietoo-cli/cmd/wietoo" = "vX.Y.Z"

Ver wietoo-cli para el resto de requisitos (mise.toml completo, lefthook.yaml, configuración de módulos Go privados).

Referencias

• wietoo-cli — guía completa del asistente/validador de commits vigente
• czg — la herramienta que usaba antes esta política (referencia histórica)
• lefthook — el hook commit-msg valida el mensaje con wietoo check-commit-msg
• wiedii-configs (wildcat/wiedii-configs) — hooks de lefthook compartidos entre todos los repos