Mejores prácticas para los comentarios de control de versión

Hay una gran cantidad de conversaciones sobre cómo comentar el código, pero ¿qué hay de comentar sobre los check-ins?

Encontré esta publicación en el blog: http://networkingbitbluebit.com/subversion-check-in-comment-great-practices/

Como el chico que está preparando las notas de la versión, estoy buscando forms de facilitar ese trabajo.

Actualmente definimos nuestro propio esquema con <Begin_Doc>...<End_Doc> para todo lo que debería publicarse para nuestros clientes de software. Pero incluso para las cosas internas, me gustaría saber el "por qué" para cada cambio.

Cada function tiene un ticket / issue / bugreport / task / whatever-you-call-it, y el número de ticket siempre se reference en el comentario de check-in. Esto da context.

Yo recomendaría NO usar / sobrecargar su sistema de control de versiones para esto. Sugeriría el software de seguimiento de problemas como un mejor ajuste.

Por un lado, no parece apropiado que los desarrolladores agreguen todo el context y la información duplicada en un post de compromiso que ya se encuentra en un documento de requisitos o en un sistema de problemas / defectos.

Puede utilizar una herramienta para recostackr los numbers de soluciones / problemas relevantes que se encuentran en los comentarios de compromiso y luego recostackrlos de su otro repository, pero creo que es un error básicamente hacer que su herramienta de revisión sea externa.

Debe definir qué es el repository de origen / versión / SVN: si se trata de la gestión de sus files de origen o si también es para escribir una nota de lanzamiento. Creo que no debería estar sobrecargado

Recomiendo comentarios funcionales Los comentarios deben dar un resumen de lo que ha cambiado. Si algo fue cambiado, y por qué. Cada compromiso debe ser explicable, si no puedes explicarlo claramente, probablemente no deberías registrarlo.

Lo más importante que debe recordar al usar los loggings de control de origen es que están allí para determinar cuándo y qué se cambió. Cuanto más funcional y detallado, mejor. los commits deben hacerse en pedazos de tamaño de mordisco, que se pueden explicar con comentarios de tamaño de bocado.

Mi preference personal es este estilo:

ACTUALIZADO el sistema de logging de errores.

  1. Se agregó una rutina de análisis de errores henetworkingados usando regex para get los códigos de error henetworkingados.
  2. Cambió el text en los posts de error de la database para corregir errores ortocharts.
  3. Se eliminaron las secciones de código comentadas, ya que no se usaron más.

Tratamos de mantenerlo simple: escriba una oración que describa el cambio que está cometiendo. Si un desarrollador necesita dos o más oraciones para describir el compromiso, entonces tal vez el compromiso es dos trabajos no relacionados. Cuando los commits como este terminan en control de versiones, entonces es difícil revertir correcciones de forma aislada.

Otra información que nos gustaría include en nuestro comentario de compromiso es el número de defecto / característica que el compromiso corrige / implementa. No todo el trabajo que hacemos se relaciona con un defecto en nuestro sistema de seguimiento de problemas, por lo que no es obligatorio.

Una última pieza de información que incluimos en los comentarios de confirmación es el nombre de un revisor de código . Esta es la persona que hizo un control de cordura sobre los cambios antes de que se lleve a cabo el compromiso.

La key es qué vas a hacer con los comentarios. Si está creando notas de la versión, puede hacer lo que sugirió. Sin embargo, recomendaría que realice un seguimiento de las notas de la versión en otro lugar, como en una herramienta de gestión de proyectos o de seguimiento de errores.

En cuanto a los comentarios relacionados con el desarrollador, generalmente pedimos a las personas que expliquen lo que están haciendo, una explicación de una oración. No es necesario que sea demasiado formal, principalmente porque si se trata de personas, se opondrá a ello. Además, si sabe quién lo hizo y tiene un comentario rápido, generalmente puede rastrear el problema y encontrar a la persona.

Además, si usa una herramienta como FogBugz , puede vincular un logging SVN a un número de caso. Lo que significa que puede consultar el caso para get una discusión completa, comentarios, capturas de pantalla, etc. que es mucho más información de la que podría ingresar en un comentario de verificación.

Acepte el Recuerdo, pero también debe escribir un poco sobre por qué implementó el cambio / corrección de errores de la manera en que lo hizo. Si cree en el logging a menudo, también debe include TO DO para que uno de sus compañeros de trabajo pueda completar la tarea.

Hacer pequeños cambios ayuda: puedo proporcionar descripciones detalladas de mis cambios de esta manera.

Los comentarios de checkin deberían ser la información que un desarrollador desea: esto incluye refactorizaciones, motivación detrás del código, etc.

En nuestros proyectos, siempre abogamos por brindar detalles sobre el compromiso y para ayudar a no tener que duplicar información como el problema, utilizamos Trac y tenemos nuestro repository integrado. La ventaja es que puede hacer reference al ticket de problema en el comentario y solo indicar la resolución o los pasos del trabajo realizado. Trac luego vincula automáticamente el número de reference al número de emisión original y aplica su post de confirmación como un comentario al problema. Luego, cuando desee ver lo que se ha hecho, simplemente puede leer los problemas dentro de Trac y tener un context completo.

Con respecto a las notas de la versión, hemos encontrado que trabajar con la list de problemas dentro de un lanzamiento y usar la información de compromiso como base para los comentarios ha funcionado bien. En general, no tendrá notas de la versión que tengan los posts de compromiso sin formatting, ya que a sus clientes realmente no les importan cada pequeño cambio o incluso el nivel de detalle que se puede include en el comentario. Por lo tanto, normalmente necesitaría hacer una buena cantidad de ediciones para resaltar los principales cambios y correcciones de errores implementados en esa versión.

Yo diría que intenté seguir un estilo de logging de cambios. La primera línea debe ser un breve resumen e include el número de problema / ticket (si corresponde). Esto posiblemente debería ir seguido de una línea en blanco, dependiendo de cómo su VCS maneja los posts de confirmación de múltiples líneas, y luego una descripción de líneas múltiples más completa. Diría que no es razonable imponer ningún formatting estricto, ya que desalienta las confirmaciones frecuentes, pero siempre que los compromisos importantes (los que cierran o los cambios importantes) se realicen de esta manera, debería estar bien.

Si usa algo como Trac o integración de resumen + svn, puede seleccionar los numbers de emisión de los posts de confirmación. Siempre pondría estos en la primera línea ya que son muy útiles.

Editar: Dado que esta es, con mucho, mi respuesta más negativa, creo que vale la pena destacar lo que está oculto en el último párrafo: soy un propietario único. Tengo el 100% de la propiedad de estos proyectos y no trabajo con otros desarrolladores. En una tienda con más de un desarrollador, todo lo que digo en esta respuesta puede ser completamente inapropiado.

Me suscribo a DRY aquí como en todas las cosas.

Casi nunca agrego un comentario a mis commits. Un comentario casi siempre se repite. La respuesta a la pregunta "¿qué cambió en este compromiso?" casi siempre está en la diferencia.

Cuando miro un file y pregunto "¿qué diablos pasó aquí?", Lo primero que hago es mirar el diff con la versión anterior. El 90% de las veces la respuesta es inmediatamente aparente, ya sea porque el código es evidente por sí mismo o porque había algo no evidente que comenté en el código. Si no es así, correlaciono las dates de rev del file con el sistema de seguimiento de errores y la respuesta está allí.

Esto siempre funciona A veces se requiere una pequeña investigación para resolver algo, porque no comenté mi código adecuadamente. Pero nunca he podido encontrar la respuesta con bastante rapidez.

La única vez que agrego un comentario al logging de confirmación es cuando sé que un diff no me va a ayudar. Por ejemplo, cuando clasifico a los miembros de una class: lo único que me dirá una diferencia en ese caso es que sucedió algo muy grande. Cuando lo hago, confirmo el file tan pronto como lo haya corregido. No hay un lugar apropiado para comentar un cambio de ese scope en el file, por lo que agrego un comentario en el sentido de que el único cambio en esta revisión es reorderar a los miembros.

("¿Por qué no comentaría un cambio como ese en el historial de revisión en la parte superior del file?", Podría preguntar. No guardo un historial de revisión en la parte superior de mis files. Eso fue un espantoso, break- El cambio del hábito de la vida es algo que nunca se debe hacer, y nunca me he arrepentido por un momento. El historial de revisión es Subversion.

Si no tuviera el 100% de la propiedad del proyecto, podría ser diferente. Puede ser muy difícil correlacionar las confirmaciones con correcciones de errores. Puede ser muy difícil capacitar a otros desarrolladores para codificar un estilo que permita confiar en el control de versiones de manera efectiva. Tendría que ver.