Nivel de detalle para usar en los comentarios de revisión de control de versión

Esto siempre me ha molestado por mucho time. Los comentarios que quedan en las revisiones son extremadamente útiles cuando vuelvo a ellos meses después; sin embargo, cuando son demasiado detallados, restan valor al objective general.

Eventualmente me decidí por un sistema simple, en el que con cada comentario agrego algunas viñetas con una label en particular, por ejemplo:

Fixed: A bug that would cause user input to be ignonetworking when calculating age. Added: Users can now set their age manually with automatic method fails. 

En general, he encontrado que funciona bastante bien: el comentario ofrece un resumen de alto nivel de lo que esta revisión intentó hacer, y para más detalles, puedo verificar el código. Sin embargo, estoy muy interesado en preguntar si alguien ha presentado su propio esquema de documentation que funciona bien para ellos y para otros.

El nivel de detalle que tienes allí es sobre lo que encontraría apropiado. El comentario de compromiso debe decir "qué" se hizo, no cómo (el código hace eso).

Para el "¿por qué?", ​​Exigiría un identificador para su sistema de seguimiento de problemas, por lo que cada confirmación hace reference a un error / mejora, etc. Usamos anzuelos precompromisos en svn para evitar cualquier confirmación que no tenga un ID JIRA válido.

Esto significa que al comparar el logging entre dos tags, podemos generar una list de problemas que definitivamente tuvieron cambios fuente hechos en ese marco de time y usar eso para producir notas de lanzamiento canónico.