¿Qué información debe contener un comentario de confirmación de archivo SVN/Versión?

Question

Tengo curiosidad qué tipo de contenido debe estar en un archivo versionado cometer comentario. En general, describa qué cambió (por ejemplo, "La pantalla del widget se modificó para mostrar solo widgets activos") o debería ser más específico (por ejemplo, "Se agregó una nueva condición a la cláusula where de la consulta fetchWidget para recuperar solo widgets activos por defecto ")

¿Qué tan atómico debe ser una única confirmación? Solo el archivo que contiene la consulta actualizada en una única confirmación (por ejemplo, "Se actualizó la pantalla del widget para mostrar únicamente widgets activos por defecto"), o si esa y otras modificaciones más cambios + interfaz a una pantalla comparten la misma confirmación con una descripción más general como ("se ha actualizado la pantalla de widgets: a) botón para alternar la presentación de los widgets inactivos pantalla sólo widgets activos por defecto B) añadió")

veo la subversión cometer los comentarios que se utilizan de manera muy diferente y se preguntaba lo que otros han tenido éxito con. Algunos comentarios son tan breves como "archivos actualizados", mientras que otros tienen muchos párrafos, y otros están formateados de manera que se pueden consultar y asociar con algún sistema externo como JIRA.

Solía ​​ser extremadamente descriptivo del motivo del cambio así como de los cambios técnicos específicos. Últimamente he estado retrocediendo y dando un comentario general de "Esto es lo que he cambiado en esta página".

Answer 1

Algunas pautas:

• no escribir cosas que el sistema VC ya se realiza un seguimiento automático: qué archivos, el número de líneas, cuándo, quién hizo el cambio ...
• escribo lo que el objetivo del cambio fue: "agregue soporte UTF-8 a las etiquetas ID3"
• si encuentra que el propósito no es claro o es múltiple, probablemente sea mejor que haga varias confirmaciones. Linus Torvalds puede salirse con la suya escribiendo "varias correcciones por todos lados"; el resto de nosotros no debería tomarlo como un ejemplo.
• si tiene algún tipo de sistema de seguimiento que asigne identificadores únicos a problemas o solicitudes de características, de ninguna manera etiquete el comentario con ese identificador.

Answer 2

Personalmente, intento hacer un breve resumen de lo que cambié y/o agregué. Algo que me recuerde, "Ah, sí, esto es [probablemente] donde agregué esa regla adicional al objeto comercial". Porque siempre puedo ejecutar un "diff" para ver específicamente qué cambió.

Answer 3

debe explicar brevemente qué contiene la confirmación. Esto debería incluir un número de ticket para corregir o mejorar un error. El mejor consejo que he escuchado sobre escribir comentarios es este "Código como si el siguiente tipo para mantener tu código es un maníaco homicida que sabe dónde vives" Esto es igualmente apropiado para enviar comentarios.

Answer 4

Una cosa que me ayuda a la hora de pensar qué escribir/qué no escribir, es que eventualmente debería ser posible compilar notas internas de la versión técnica de los comentarios de confirmación.

También me resulta muy útil para establecer las etiquetas en los comentarios cometer, como #doc, #typo, #refactor, ...

yo no estaría demasiado descriptiva en la comisión - las razones para hacerlo algo de una manera u otra debería estar en la documentación, o en los comentarios del código IMO.

Answer 5

Los comentarios de compromiso útil son aquellos que agregan información útil que no se extrae fácilmente de los cambios mismos.En cuanto a los diferenciales mostrará lo que ha cambiado, por lo que el mensaje de consignación debe concentrarse en la explicación de por qué se hicieron los cambios:

• Fijo accidente debido a la referencia a un puntero NULL (error 234).

• Comando agregado para desconectarse del servidor (solicitud de función 22).

• Código limpio para futuros cambios.

Otra clase útil de comentario es el que resume el propósito general de un conjunto más amplio de cambios:

• Añadido soporte para permitir al usuario frobulate el widget.

Answer 6

Si utiliza un sistema de seguimiento de errores, es mejor incluir el error/mejora # en el que está trabajando que se aplica al cambio. Muchas veces, simplemente volverás a escribir lo que está en la descripción del error de todos modos.

Answer 7

Debe contener un pequeño resumen de los cambios (para permitir el filtrado en una lista de cambios) y por qué se aplica el cambio.

La documentación del nuevo código pertenece al código fuente en sí; no en el mensaje de registro. (Y comenta que solo aplicado al código anterior debe eliminarse. Siempre puede ver esos comentarios antiguos a través del historial de su sistema SCC).