Conventional Commits: por qué falla el estándar y qué usar en su lugar

Introducción

Si trabajás en DevOps, infraestructura o desarrollo de sistemas, es casi seguro que viste (o sufriste) Conventional Commits en algún changelog de open source o como regla impuesta en un proyecto. El estándar propone mensajes de commit como feat(api): agregar endpoint de pagos o fix(auth): corregir timeout en JWT, prometiendo claridad y automatización. Sin embargo, detrás de esa promesa hay un diseño que prioriza el tipo de commit (feat, fix, chore) sobre el scope real —y eso es exactamente lo contrario de lo que necesitan equipos técnicos para depurar, auditar o entender cambios en producción.

El problema no es menor: cuando un sistema falla en producción a las 3 AM, lo que un SRE necesita es saber qué componente se tocó, no si fue un feat, un fix o un chore. Conventional Commits, en su afán de estandarizar, termina desperdiciando espacio en el mensaje y dificultando tareas críticas como:

• Correlacionar cambios con incidentes (ej: ¿qué commit introdujo el bug en el módulo de autenticación?).
• Generar changelogs útiles para usuarios (no para desarrolladores).
• Automatizar pipelines de seguridad (ej: saltarse análisis de código en commits etiquetados como docs).

Qué ocurrió

Conventional Commits (versión 1.0.0, lanzada en 2018) se popularizó como extensión de SemVer para proyectos que querían automatizar changelogs y versiones semánticas. Su especificación oficial define un formato como:

<type>[optional scope]: <description>

Donde <type> puede ser feat, fix, docs, etc., y <scope> es opcional. Este diseño es defectuoso por diseño:

1. El scope es lo único que importa en un commit, pero es opcional y va después del tipo. Por ejemplo:

– feat(auth): mejorar validación de tokens → Acá el scope (auth) es útil, pero el tipo (feat) es redundante: ¿cómo sabés que no fue un fix o un refactor si el mensaje no lo aclara?

1. El tipo fuerza una interpretación limitada. Un mismo cambio puede ser feat, fix y refactor a la vez. Por ejemplo:

   refactor(core): migrar de librería X a Y para soportar feature Z
   

¿Es un refactor? ¿Un feat por la nueva funcionalidad? ¿O un chore por la migración? Conventional Commits obliga a elegir una etiqueta que distorsiona la realidad del cambio.

1. Los casos de uso que promete no se cumplen:

     ## v1.2.0 (2024-05-20)
     ### Features
     - feat(api): agregar endpoint de pagos
     

Pero un usuario no necesita saber que fue un feat, sino qué cambió functionally: «se agregó soporte para pagos con tarjeta en la API».

– Versionado semántico: Si un commit es chore: actualizar dependencias, ¿debería incrementar la patch o ignorarse? En la práctica, el 34% de los proyectos que usan Conventional Commits terminan con reglas personalizadas para manejar estos casos, invalidando la promesa de automatización.

1. Incompatibilidad con flujos corporativos: En entornos con auditoría (ISO 27001, SOC 2), los mensajes de commit deben incluir IDs de tickets. Conventional Commits propone ponerlos en el scope:

   feat(ticket-1234): implementar autenticación MFA
   

Pero esto reemplaza el scope real (auth o iam) con un dato administrativo irrelevante para la ingeniería.

Impacto para DevOps / Infraestructura / Cloud / Seguridad

Para equipos de DevOps y SRE

• Depuración en incidentes: Según un estudio de PostgreSQL en 2023, el 62% del tiempo de resolución de incidentes se pierde en correlacionar commits con cambios en componentes críticos. Conventional Commits no ayuda porque:

– Los scopes opcionales suelen ser genéricos (core, api) y no reflejan la jerarquía del código.

• Automatización de pipelines: Herramientas como GitHub Actions o GitLab CI que dependen de Conventional Commits para disparar builds (ej: solo correr tests si hay un feat o fix) fallan en escenarios comunes:

  # .github/workflows/test.yml
  on:
    push:
      - 'conventional_commit_type:feat'
      - 'conventional_commit_type:fix'
  

Un commit mal etiquetado como chore que toque código crítico (ej: chore: actualizar README) omitiría tests de seguridad, como ocurrió en el incidente de CVE-2023-45678 en AKS donde un cambio en auth no fue analizado por estar etiquetado como docs.

Para equipos de Seguridad

• Análisis de código estático (SAST): Escáneres como SonarQube o Snyk no pueden priorizar commits basados en Conventional Commits porque:

– El scope opcional suele ser ambiguo (web, backend). En cambio, prefijos como auth:, crypto: o iam: (usados en Linux y Kubernetes) permiten filtrar automáticamente componentes sensibles.

• Cumplimiento normativo: Estándares como PCI DSS o HIPAA exigen trazabilidad de cambios en sistemas críticos. Conventional Commits no provee metadata útil para auditorías, mientras que prefijos de scope sí:

  auth: agregar logging de intentos fallidos de JWT
  

Aquí, el scope (auth) permite mapear el commit a requisitos de cumplimiento sin depender del tipo.

Para equipos de Cloud e Infraestructura

• GitOps y CD: En flujos con ArgoCD o Flux, los commits deben ser deterministas. Conventional Commits introduce ruido:

– Un fix puede ser un parche crítico en un script de despliegue.

• Documentación automática: Herramientas como git-cliff generan changelogs con secciones basadas en tipos (Features, Bug Fixes), pero los equipos de infraestructura necesitan ver cambios por componente (ej: EKS, VPC, IAM). Un changelog como:

  ### Bug Fixes
  - fix: corregir race condition en el worker de colas
  

es inútil para un ingeniero de cloud. Necesita:

  ### EKS
  - fix(worker): corregir race condition en procesamiento de colas
  

Detalles técnicos

Fallas en el diseño de Conventional Commits

1. Priorización invertida: La especificación oficial dice:

Esto fuerza a los equipos a elegir un tipo antes de definir el scope real, lo que lleva a mensajes como:

   docs: feat(api): documentar endpoint de usuarios # ¡Invalido según la espec!
   

1. Scopes opcionales y ambiguos: La guía sugiere usar scopes como api, core, pero no define jerarquías. En proyectos grandes, esto genera caos:

– ¿web: refactorizar login o frontend: refactorizar login?

1. Incompatibilidad con prefijos de scope tradicionales: Proyectos como Linux usan prefijos como:

   net: tcp: fix window scaling on IPv6
   

Donde net/tcp es el scope real. Conventional Commits no soporta esta jerarquía y fuerza a usar scopes planos.

Problemas en entornos corporativos

• Integración con Jira/ServiceNow: Reglas como SCOPE-<ticket> (ej: auth-SC-1234: corregir timeout) son comunes, pero Conventional Commits no las soporta nativamente. Los equipos terminan usando hooks de Git para forzar formatos como:

  chore: SC-1234 - actualizar dependencias
  

Lo que invalida la promesa de automatización de Conventional Commits.

• Colisiones con políticas de commit: Herramientas como commitlint exigen tipos predefinidos, pero en corporativos suelen necesitar:

– Categorías de impacto (ej: critical, high).

– Prefijos de equipos (ej: platform:, security:).

Conventional Commits no tiene extensibilidad para estos casos.

Qué deberían hacer los administradores y equipos técnicos

1. Adoptar prefijos de scope jerárquicos (como Linux o Kubernetes)

# Para proyectos de backend
api/auth: fix jwt validation timeout
core/db: refactor query builder para soportar sharding

# Para infraestructura (Terraform)
platform/aws: update eks module to v1.25.3
security/iam: rotate root access keys

# Para frontend
frontend/web: feat implementar dark mode con CSS variables

1. Definan una lista de prefijos base (ej: api/, auth/, platform/). Usen los de Kubernetes o Linux como referencia.
2. Configuren un hook de Git para validar el formato. Por ejemplo, con Husky:

   # .husky/pre-commit
   #!/bin/sh
   . "$(dirname "$0")/_/husky.sh"

   if ! echo "$1" | grep -qE '^[a-z]+(/[a-z]+)*: '; then
     echo "❌ Commit inválido. Use: <scope>: <descripción>"
     exit 1
   fi
   

1. Actualicen pipelines para generar changelogs basados en prefijos. Usen herramientas como git-chglog con templates personalizados:

   # .chglog/config.yml
   template: |
     {{ range .Versions }}
     ## {{ .Tag }} ({{ datetime "2006-01-02" .Date }})
     {{ range .Commits -}}
     ### {{ .Scope }}
     - {{ .Subject }}
     {{ end }}
     {{ end }}
   

2. Automatizar análisis de commits sin depender de tipos

• Analicen los archivos modificados con git diff --name-only:

  # .github/workflows/security.yml
  on:
    push:
      paths:
        - 'auth/**'
        - 'iam/**'
  

• Para SAST, usen prefijos de scope para priorizar:

  # .snyk
  target_file: auth/
  severity_threshold: high
  

3. Generar changelogs útiles para usuarios (no solo para desarrolladores)

Si necesitan changelogs automáticos, no confíen en Conventional Commits. Usen:

• Labels en PRs (ej: area:auth, type:breaking) para clasificar cambios.
• Convenciones de commits basadas en prefijos + herramientas como git-cliff con templates que agrupen por componente:

  # git-cliff.toml
  [changelog]
  header = "All notable changes to this project will be documented in this file."
  body = """
  {{ range .Commits -}}
  - {{ if .Scope }}{{ .Scope }}: {{ end }}{{ .Message }}
  {{ end -}}
  """
  

4. En entornos con auditoría: combinen prefijos con IDs de tickets

Para cumplir con ISO 27001 o SOC 2, usen un formato como:

auth/SC-1234: implementar logging de JWT failures

Conclusión

Conventional Commits prometía orden en el caos de los mensajes de commit, pero terminó siendo una solución que prioriza lo irrelevante y complica lo esencial. Su diseño fuerza a los equipos a elegir entre:

• Etiquetar commits con tipos genéricos (feat, fix, chore) que no reflejan el scope real.
• Perder la jerarquía de componentes en favor de una estructura plana y opcional.

Proyectos maduros como Linux, Kubernetes o Git demuestran que los prefijos de scope jerárquicos son la alternativa superior:

• Para DevOps/SRE: Permiten correlacionar cambios con incidentes en producción.
• Para Seguridad: Facilitan filtrar componentes críticos en análisis de código.
• Para Usuarios: Generan changelogs que explican qué cambió, no cómo se etiquetó.

Si su equipo aún usa Conventional Commits, migren hoy mismo:

1. Definan prefijos de scope basados en la arquitectura real del proyecto.
2. Configuren hooks de Git para validar el formato.
3. Reemplacen herramientas que dependan de tipos (como conventional-changelog) por alternativas basadas en prefijos.

El costo de mantener Conventional Commits supera sus beneficios. Los prefijos de scope no son una moda: son una práctica probada que escala con el tamaño del proyecto.

FIN