¿Qué debo poner en los comentarios al comprometerme con el Control de código fuente?

Soy un desarrollador solitario y mantengo un servidor SVN para el control de código fuente. Hasta ahora, no he seguido nada específico al comprometer mis cambios.

Solo estaba revisando mis confirmaciones anteriores, y no podía entender mis comentarios.

¿Qué pones en los comentarios al confirmar tus registros?

Puede que le interese leer esto: /programming/321720/best-practices-for-version-control-comments .

Si no está utilizando un rastreador de errores y, como tal, no puede incluir una identificación / número de informe de errores, debe ser muy descriptivo en sus comentarios. De lo contrario, si solo escribe "problema solucionado con X", por ejemplo, dos semanas después de la confirmación, no recordará cuál fue el problema. En ese caso, deberá comparar las versiones de confirmación antes y después para comprender de qué se trataba.

Cuando comencé a desarrollar aplicaciones profesionalmente, no utilizamos un rastreador de errores, y puedo recordar que a veces los comentarios eran muy descriptivos (incluso demasiado), a veces no había ningún comentario, era un desastre. Con una identificación del rastreador de errores, los comentarios son mucho más útiles y con algunas palabras más puede incluso indicar por qué realizó ese cambio en particular. Además, IDE como Eclipse, por ejemplo, tienen complementos que detectan la identificación del rastreador de errores en los comentarios (y también en el código fuente) y pueden proporcionar un enlace en el que se puede hacer clic en la página web del rastreador de errores.

¿Qué esperabas encontrar en los comentarios de tus commits anteriores?

Simplemente ponga esa información en sus próximas confirmaciones.

A veces, un ID de ticket es suficiente, un ticket que representa un informe de error o una solicitud de función.

Los comentarios de compromiso se refieren a ver fácilmente lo que se cambió. Están allí para su referencia, por lo que la cantidad de detalles que ponga dependerá de cuánto esfuerzo quiera dedicar ahora para ahorrar tiempo en el futuro. En términos generales, un pequeño esfuerzo en el tiempo de compromiso tiene el potencial de ahorrar mucho tiempo en el futuro.

Por ejemplo, dicen que cambió una <=a una >y una ++a una --en un bucle, pero no añadió un comentario descriptivo cometer. Más tarde, sería difícil encontrar la revisión donde invirtió la dirección de la iteración. Si hubiera comentado " Dirección inversa del recorrido del índice bla ", entonces sería mucho más fácil encontrar esa revisión buscando en el registro de revisiones.

Es por eso que incluir información de seguimiento de problemas en los mensajes de confirmación es una muy buena idea. Supongamos que soluciona un error, luego el problema se vuelve a abrir porque no se solucionó por completo. Si su comentario de confirmación de la solución original menciona el identificador del rastreador de problemas, puede encontrarlo fácilmente y luego aún puede encontrar fácilmente todas las revisiones asociadas con ese problema.

Tiendo a escribir una forma concisa de lo que estoy cometiendo; si es para una tarea específica, incluiré el número de tarea en el mensaje. Cosas como:

Changed foobar module to account for the new baz; created quux pages and data objects.

Lo que no debe hacer es escribir algunas tonterías como "Vaya" o "Comentarios agregados" (los cuales he visto agregados en los registros de confirmación por un compañero de trabajo), o lo peor de todo es hacer algo como lo vi el otro día - A el archivo único se registró con el mensaje de confirmación "Comentario" (cotización exacta). ¿Qué se agregó, puede preguntar? Algo en el sentido de:

if (z == true) { 
    x = y; // x is being overridden here... <--- added in commit
}

Y no, no nos mide la cantidad de confirmaciones.

Creo que todo esto se reduce a cómo manejas tus proyectos. Para mí, tiendo a comprometerme cada vez que termino una característica que quiero impulsar a una versión de lanzamiento. Como en mi caso, cada función resulta en una confirmación, utilizo la historia de mi función y el número de problema como mi comentario. Lo mismo vale para corregir errores. Comienzo con un pico, deduzco una historia, utilizo la historia para describir los cambios que necesito hacer y una vez más me comprometo a controlar la fuente con una historia en los comentarios.

ID del problema.

La mayoría de los rastreadores de problemas tienen un formato en el que pueden analizar las identificaciones de problemas a partir de mensajes de confirmación y las confirmaciones grupales con problemas.

Si no usa un rastreador de problemas, debería hacerlo, no importa que sea un desarrollador en solitario, he explicado el asunto en otra respuesta :

Use un rastreador de problemas. No importa que seas un lobo solitario, realiza un seguimiento de todo lo que haces para tu proyecto, ya sea una característica o un error. Haga una lista de características / componentes. Marque los componentes verdaderamente esenciales como la versión 1.0 y todo lo demás como la versión 2.0. Y luego elimine todo lo que está marcado como 2.0.

Ok, dado que la pregunta recibió una notificación de modificación para respuestas más largas, me siento obligado a expandir:

Sí, acabo de poner el ID del problema en los comentarios de confirmación, nada más. Es entonces cuando en proyectos en solitario, en proyectos en equipo es otra historia. No estoy abogando por poner solo la identificación del problema, debería haber algo más allí, pero:

1. En proyectos en solitario es extremadamente tentador no documentar nada,
2. Poner la ID del problema significa de forma predeterminada que ha pasado por el proceso de configuración de un rastreador de problemas,
3. Eso es lo suficientemente bueno para mí.

Usar un rastreador de problemas de manera efectiva cuando se desarrolla solo es un logro mucho más grande que enviar comentarios. Sería bueno si tuviera la motivación para agregar algo útil en los comentarios, pero no lo hago.

Generalmente pongo el propósito del check-in en la parte superior. Este puede ser el nombre de una solicitud de función, número de ticket, etc.

Luego lo sigo con la lista de los archivos afectados y los cambios específicos requeridos en cada archivo. Esto es particularmente útil cuando uno está mirando el historial de revisión de un archivo en lugar del proyecto / carpeta.

Algo como

Ticket 101 fix web service exception when uploading widget

Bug was caused by users uploading incomplete widgets (widgets without wonkers)

webservice.cs:  
  improved post validation for incomplete widgets
  added default exception handler to ProcessWidget
widget.cs:  handled the SqlException when inserting widgets without wonkers

En general, lo que trabajó en esa confirmación es un buen comienzo :)

(por curiosidad ... ¿qué has estado escribiendo si no pudiste entenderlo?)

Los cambios que ha realizado en el código y cualquier otra cosa que pueda ser relevante incluyen, entre otros, correcciones de errores, nuevas funciones, interrupciones en la funcionalidad, cambios en las bibliotecas, etc. Por supuesto, ya que el código se confirma en pequeños incrementos. No tendrá todo lo anterior. Por ejemplo, si está arreglando un error, puede hacer varios cambios. Estos serán múltiples confirmaciones para corregir el error, pero qué cambios realizó para corregir el error en particular.

El bit de información más importante en el registro de confirmación es el 'por qué', no el 'qué'.

Un breve resumen de los cambios puede ser útil, pero generalmente puede obtener esa información desde el propio diff. No es un gran problema si eso falta.

Mirando hacia atrás en un registro de confirmación, querrá saber por qué se realizó ese cambio. Una identificación de error puede ser muy útil para responder esa pregunta. A veces se requieren más explicaciones. Por ejemplo, si arregla una sonda en una entrada incorrecta, explique qué entrada causó el problema y, si no es trivial, también cómo podría ocurrir.

Estamos usando assembla en nuestro proyecto. Construimos el cardwall con todos los errores / fallas que deben hacerse y cuando nos comprometemos simplemente nos referimos a este ticket

Por ejemplo:

see #243
 - Grid listed all users with an income more then 1000$ but not the ones that have
   exactly 1000. Added a >= in the file xy.cs on the line xyz

De esta manera, podemos identificar los cambios más rápido y encontrar algunos errores más fácilmente