Estándar para documentación de Commits
 Warning: | Esta página define el estándar para documentación de commits en repositorios GIT. Su aplicación dentro de las actividades diarias es de uso obligatorio para todos los miembros del área de Desarrollo. |
Este estándar se establece con la intención de generar documentación de utilidad al momento de registrar commits en los repositorios GIT, además de permitir a la Project Manager generar métricas de productividad que puedan ser enviadas a la gerencia de Telstock.
Los pasos para adaptarse al estándar son los siguientes:
- Estandarizar el usuario con el que están apareciendo los commits en el [SCM Manager].
- Documentar los commits de acuerdo al estándar establecido.
Cambiar usuario y correo con el que se registran los Commits
Dado que en muchos casos se usa GitHub Desktop como cliente Git, en los repositorios clonados queda seteado un usuario asociado a la plataforma de GitHub, el cual es distinto del usuario corporativo asignado para el SCM Manager.
Es por ello que se hace necesario verificar que el usuario con el que se están realizando los commits en el repositorio es el corporativo, por ejemplo:
- Para el usuario corporativo rbabilonia el correo asociado es rbabilonia@telstock.net
- Por lo que los commits deben aparecer firmados como: Robert Babilonia <rbabilonia@telstock.net> y no con cualquier otra cuenta o correo electrónico.
Para verificar el usuario con el que se están firmando los commits, ejecutar el siguiente comando desde una consola en el directorio raíz del proyecto Git:
git config --global --list
Esto retornará la lista de configuraciones globales asociadas a Git:
Nota: Si el nombre y correo están seteados correctamente en estas variables, verifique la configuración particular para el repositorio del proyecto desde el que realiza la consulta, para ello ejecute:
git config --list
Esto retornará los parámetros de configuración asociados al repositorio.
Donde los parámetros mas importantes serán:
- user.email
- user.name
Si en alguno de los casos el usuario o correo no están correctamente configurados, los puede corregir con las siguientes lineas desde el batch:
// Para configurar nombre y correo de forma global git config --global user.name 'John Doe' git config --global user.email 'john@doe.org' //Para configurar nombre y correo solo para el repositorio desde donde se ejecuta este comando git config user.name 'John Doe' git config user.email 'john@doe.org'
Registrar commits según el estándar Telstock
La información de los commits es importante para poder llevar un mejor control de las actividades y niveles de productividad de los participantes de un proyecto. Es por ello que se ha definido el siguiente estándar para garantizar que se dispone de la información mínima necesaria.
Esta documentación usa como base la consola Git Batch, sin embargo, puede usar cualquier cliente git para enviar sus commits, siempre y cuando se adapte al estándar acá definido
Todo commit en Git debe llevar un mensaje asociado, este mensaje debe tener la siguiente estructura:
[Código Mantis o Jira] - [Mensaje descriptivo]
Donde [Código Mantis o Jira] debe ser sustituido por el código de la actividad asociada en el Jira o el número del ticket en el Mantis:
Ejemplo para Jira:
Como se observa en la imagen, el código de la actividad asociada es DCDBM-21, por lo que el mensaje de commit correspondiente sería:
DCDBM-21 - [Mensaje descriptivo]
Ejemplo para Mantis:
Para este ejemplo, el ticket de Mantis asociado es el 111, por lo que el mensaje de commit correspondiente sería:
MANTIS-111 - [Mensaje descriptivo]
Usando la consola Git Batch el commit se vería así:
git commit -m 'DCDBM-21 - Mensaje de prueba para documentar estándar de mensajes de Commits en repositorios'
El resultado en el repositorio remoto luego de hacer push será:
Se puede apreciar en la imagen que tanto el correo electrónico como el mensaje del commit están apegados al estándar definido para la documentación de los commits.
¿Qué hago si mi commit no está asociado a un ticket o solicitud en particular?
Note que esto es sólo para casos excepcionales ya que toda actividad realizada debe estar casada con su código de Jira o Mantis correspondiente.
Siempre será necesario que los cambios realizados sobre los repositorios de código fuente estén soportados por un Ticket o Solicitud de Mantis o Jira, sin embargo en los casos en los que esto no sea posible, ya sea porque se están realizando configuraciones del proyecto o correcciones detectadas para saldar deuda técnica, se podrá usar la expresión Sin Ticket para acompañar el mensaje de commit:
[Sin Ticket] - [Mensaje descriptivo]
