Saltar al contenido principal

Convención de Nombres para Commits, Ramas y Pull Requests

Objetivo​

El objetivo de este documento es establecer un estándar único y sencillo para nombrar commits, ramas y pull requests, de modo que cada cambio en el repositorio esté claramente asociado a una US de ClickUp y se mantenga la trazabilidad de los desarrollos. La convención se basa en los principios de conventional commits pero se simplifica para usar únicamente tres tipos: feat, fix y docs.

Requerimientos Comunes​

Para commits, ramas y pull requests se debe incluir:

  1. ID de la US de ClickUp:
    • Cada nombre debe incluir el identificador único de la US (por ejemplo, 86b44h2uw), para garantizar la asociación del cambio con el ticket correspondiente.
  2. Mini descripción:
    • Se deberá incluir una breve descripción del trabajo que se va a realizar o de la US a la que se asocia.
  3. Tipo de cambio:
    • Se utilizarán únicamente los siguientes tipos:
      • feat: Para nuevas funcionalidades o mejoras significativas.
      • fix: Para corrección de errores.
      • docs: Para cambios en la documentación.
    • Nota: Los nombres de las ramas, commits y pull requests deben estar en inglés, lo que incluye tanto el prefijo de tipo como la descripción.

Convenciones Específicas​

1. Ramas​

  • Sintaxis:
<tipo>_<clickupID>_<descripción>
  • Detalles:
    • Formato: Se utilizan guiones bajos (_) como separador para evitar conflictos con rutas o directorios.
feat_86b44h2uw_new_login_feature
      • Componentes:<tipo>: Debe ser feat, fix o docs.
    • <clickupID>: Identificador único de la US en ClickUp.
    • <descripción>: Breve descripción en snake_case que resuma la tarea.

2. Commits​

  • Sintaxis:
<tipo>: <clickupID> - <descripción>
  • Detalles:
    • Formato: Se utiliza el formato de conventional commits, adaptado a nuestros requerimientos.
  feat: 86b44h2uw - add user authentication
      • Componentes:<tipo>: feat, fix o docs.
    • <clickupID>: El ID de la US de ClickUp.
    • <descripción>: Mensaje breve y en modo imperativo, describiendo el cambio realizado.

3. Pull Requests​

  • Sintaxis:
<tipo>: <clickupID> - <descripción>
  • Detalles:
    • Formato: La nomenclatura para pull requests es casi idéntica a la de los commits para facilitar la identificación y asociación.
  feat: 86b44h2uw - implement authentication module
      • Componentes:<tipo>: feat, fix o docs.
    • <clickupID>: El ID de la US.
    • <descripción>: Breve descripción del contenido o propósito del pull request.

Consideraciones Adicionales​

  • Consistencia y Trazabilidad:
  • Todos los cambios deben estar directamente asociados a una US en ClickUp mediante el ID, lo que facilitará el seguimiento y la revisión de tareas.
  • Claridad en la Descripción:
  • La mini descripción debe ser lo suficientemente clara para entender el propósito del cambio sin necesidad de revisar el detalle completo de la US. Evita descripciones excesivamente largas o ambiguas.
  • Uso Exclusivo de Inglés en Nombres:
  • Es imperativo que tanto el tipo, la descripción y el ID (en el contexto de nombres) se mantengan en inglés. Esto ayudará a estandarizar la comunicación entre equipos internacionales y a mantener un repositorio consistente.
  • Buenas Prácticas de Git:
    • Utiliza mensajes de commit claros y descriptivos.
    • Evita sobrecargar el título del pull request; usa la descripción para detallar información adicional.
    • Revisa que los nombres de las ramas no contengan caracteres problemáticos (por ejemplo, evita /, espacios o caracteres especiales).

Ejemplos Prácticos​

  • Rama:
feat_86b44h2uw_new_payment_gateway
  • Commit:
fix: 86b44h2uw - correct typo in payment module
  • Pull Request:
docs: 86b44h2uw - update readme with installation instructions

Conclusión​

La adopción de esta convención de nombres asegurará que cada cambio en el repositorio esté claramente vinculado a una US de ClickUp y que el proceso de desarrollo sea más transparente y organizado. Asegúrate de que todos los colaboradores del proyecto estén familiarizados con este estándar para mantener la coherencia y facilitar la integración y revisión del código.