2008-11-26 13 views
20

Hay una gran cantidad de conversaciones sobre cómo comentar el código, pero ¿qué hay de comentar sobre los check-ins?Mejores prácticas para los comentarios de control de versión

me encontré con esta entrada del blog: http://redbitbluebit.com/subversion-check-in-comment-great-practices/

Como el tipo que está armando las notas de la versión, estoy buscando la manera de hacer que el trabajo sea más fácil.

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

Respuesta

21

Cada característica tiene un ticket/issue/bugreport/task/whatever-you-call-it, y siempre se hace referencia al número del ticket en el comentario del check-in. Esto da contexto.

+1

hacer su ambiente de trabajo para que pueda ir directamente desde el registro de entrada comentario al ticket. Una forma típica es hacer que se pueda hacer clic en el número del ticket. –

9

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 contexto y la información duplicada en un mensaje de confirmación que ya se encuentra en un documento de requisitos o en un sistema de emisión/defecto.

Puede usar una herramienta para recopilar las correcciones relevantes/números de problema que están en los comentarios de compromiso y luego recopilarlos de su otro repositorio, pero creo que es un error básicamente convertir su herramienta de revisión en externa .

Debe definir qué es el repositorio de origen/versión/SVN, ya sea para gestionar sus archivos fuente o también para escribir notas de publicación. Creo que no debería estar sobrecargado

2

La clave 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, en general, hemos pedido 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 utiliza una herramienta como FogBugz, puede vincular un registro de SVN a un número de caso. Lo que significa que puede consultar el caso para obtener 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.

0

Yo diría que trato de seguir un estilo de registro de cambios. La primera línea debe ser un breve resumen e incluir 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 mensajes 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 formato 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 así como Trac o integración de resumen + svn, puede seleccionar números de problema de los mensajes de confirmación. Siempre pondría estos en la primera línea ya que son muy útiles.

2

De acuerdo con Remembrance, 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 proceso de facturación con frecuencia, también debe incluir TO DO para que uno de sus compañeros de trabajo pueda completar la tarea.

-3

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 confirmaciones. 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 archivo 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 fechas de rev del archivo 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 registro de confirmación es cuando sé que un diff no me va a ayudar. Por ejemplo, cuando clasifico a los miembros de una clase: lo único que me dirá una diferencia en ese caso es que sucedió algo muy grande. Cuando lo hago, confirmo el archivo tan pronto como lo haya corregido. No hay un lugar apropiado para comentar un cambio de ese alcance en el archivo, por lo que agrego un comentario en el sentido de que el único cambio en esta revisión es reordenar a los miembros.

("¿Por qué no comentar un cambio como ese en el historial de revisión en la parte superior del archivo?", Podría preguntar. No guardo un historial de revisión en la parte superior de mis archivos. Dando miedo, cambiar el hábito de la vida de un cambio para hacer, y nunca me he arrepentido por un momento. El historial de revisión es Subversion.)

Si no tuve 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.

+0

tengo curiosidad sobre si su postura ha cambiado en los dos años desde que ha publicado esto. –

+0

En su mayor parte, no. Estoy poniendo la información de cronometraje en los comentarios de check-in en un par de proyectos ahora para que yo pueda hacer mi facturación por mirar el registro de confirmación - que eso me ha salvado de tener que mantener un registro de la hora normal por separado. Pero aún no he necesitado usar comentarios de registro para lo que supongo que es su propósito. Sospecho que esta respuesta recibió un montón de votos negativos de personas que no leyeron la primera oración del último párrafo. Mi culpa por haber enterrado al lede. –

+0

Gracias por el seguimiento. Y creo que tienes toda la razón sobre los votos a la baja: sé que no fue hasta que tuve éxito que tuve un momento 'ah, ja'. Tal vez editar para agregar un poco de énfasis a esa frase? –

3

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 puede explicarlo claramente, probablemente no debería verificarlo.

Lo más importante que debe recordar al usar los registros de control de origen es que están ahí para determinar cuándo y qué fue cambiado 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 preferencia personal es este estilo:

ACTUALIZADA el sistema de registro de errores.

  1. Se ha agregado una rutina de análisis de errores legacy usando regex para obtener los códigos de error heredados.
  2. Cambió el texto en los mensajes de error de la base de datos para corregir errores ortográficos.
  3. eliminado comentada secciones de código, ya que no se utilizan más.
1

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

Los comentarios deben ser checkin la información que un desarrollador quiere: esto incluye refactorizaciones, la motivación detrás del código, etc.

4

Tratamos de mantenerlo simple: escribir una frase que describe el cambio que se está cometiendo. Si un desarrollador necesita dos o más frases para describir la confirmación, entonces tal vez el envío de datos es de dos piezas sin relación de trabajo. 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 incluir en nuestro comentario de confirmación es el número de función/defecto que la confirmación 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 ponemos en nuestros 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.

1

En nuestros proyectos siempre abogado que preste algún detalle a qué comprometerse es sobre y para ayudar en no tener que duplicar la información como el problema que utilizar Trac y tenemos nuestro repositorio integrado. La ventaja es que puede hacer referencia 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 referencia al número de emisión original y aplica su mensaje 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 contexto completo.

En lo que respecta a las notas de versión que hemos encontrado que tomar la lista de cuestiones dentro de una liberación y uso de la información como base para los comentarios cometen ha trabajado bien. En general, usted no tendrá notas de la versión que tienen la materia prima cometer mensajes en ellos como sus clientes no les importa cada pequeño cambio o incluso el nivel de detalle que se puede incluir 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.

Cuestiones relacionadas