Buenos comentarios sobre sets de cambios en sourcecontrol

Necesitamos desarrollar pautas para escribir comentarios cuando registramos código en el sistema de control de versiones (como TFS).

Por ejemplo, cuando enviamos una corrección de error, creamos un comentario "Error fijo # …"

Intentamos hacer una lluvia de ideas sobre este tema, pero la mayoría de las ideas aportan muy poco valor agregado.

Agradecería cualquier sugerencia para esto.

En general, los comentarios que hacemos donde trabajo son una descripción general rápida de los cambios que se realizaron. Algo corto y simple

Puede que no parezca agregar mucho valor inicialmente, pero puede ser muy útil cuando se retrocede en la historia tratando de encontrar cuándo algo cambió (mucho más que solo "error #####"). Hubo algunas ocasiones en las que tuve que volver al historial de control de la fuente para tratar de encontrar cuándo un comportamiento en particular o un fragment de código cambió, y las descripciones rápidas pueden hacer que sea mucho más fácil rastrear dónde podría estar. Si acaba de dar un número de error, entonces tiene que trabajar más para encontrar esa información básica (busque el rastreador de errores y encuentre el error).

Mi (bastante concisa) guía sobre este tema es "documentar por qué estás haciendo el cambio, no qué ".

Es decir, no debería decir "error reparado en MyClass.cs y FooBar.cs" porque ese comentario es bastante irrelevante; pueden ver el set de cambios para encontrar esos detalles. Igualmente con TFS, la vinculación de los sets de cambios a los elementos de trabajo significa que include la reference del elemento de trabajo en el comentario es bastante superfluo. En cambio, una frase corta que explique el motivo del cambio, como "vulnerabilidad XSS potencial fija en el editor", es lo más útil para leer cuando se analiza una gran historia de sets de cambios.

Para ver un cambio que se mencionará en las Notas de la versión, incluya una input de Notas de la versión sugerida , ya sea en el comentario del set de cambios o en el informe de errores vinculado, si hay alguno.

Al escribir una input de Release Notes, se ve obligado a dar un paso atrás y observar la edición desde el punto de vista del usuario. Esto lo alienta a describir sucintamente cuál fue el problema y cómo el arreglo resuelve el problema.

Puede configurar TFS para requerir que cualquier verificación de código tenga una tarea TFS asociada.

El equipo del proyecto que lo usa donde trabajo requiere que todos los errores y / o características se ingresen en TFS como tareas, y que cualquier verificación de código se asocie con las tareas a las que se aplica.

También se requiere un comentario, pero no tienen pautas estrictas para lo que usted escribe, excepto para observar si no es necesario que el cambio se fusione a otra sucursal.

Si el cambio tiene un ticket asociado en alguna parte o un error, en ese caso el número y el título (con un enlace) deberían ser suficientes.

De lo contrario, simplemente indique qué cambio implementó. Se aplican las pautas habituales para comentarios, puede consultar algunos loggings de proyectos populares para ver buenos ejemplos.

Siempre que sea posible (como cuando se utiliza TFS para el seguimiento de errores y el control de origen) vincule el logging directamente con un elemento de trabajo apropiado. En su defecto, agregue el elemento de trabajo / error en los comentarios del set de cambios. Este es el mínimo nivel aceptable de comentarios changeset.

El comentario de verificación debe describir la intención del cambio realizado, solo agregar detalles sobre la forma en que el cambio logra los resultados deseados según sea necesario. Un buen punto de partida sería el título del elemento de trabajo apropiado.

Una o dos oraciones es una buena longitud del objective para el comentario. No seas tan general, el comentario no tiene sentido (p. Ej., "Se corrigió un error en xyz"), pero tampoco ocultes la intención del cambio bajo capas de detalles innecesarios.

Me gustaría include una reference al error (ticket, problema, como quiera que se llame) si es posible porque proporciona el context y la motivación para el cambio. Además, me gusta tratar de responder las preguntas Lo que ha cambiado y Por qué lo más cerca posible de una línea. Al hacer el comentario, trato de pensar en mi yo futuro en 6 meses mirando los loggings, el diferencial y el ticket para entender qué demonios estaba pensando. Entrar en demasiados detalles nunca parece ayudar.

+1 para pegar el título de problema de error, que debe ser informativo.

+1 para documentar por qué, si es necesario, además del título del error.

+1 por ser consciente de las notas de la versión para cuando desea informar a los clientes.

+1 para integrar SCM, seguimiento de errores y CI, y hacer que se vinculen entre ellos en problemas / errores.