version control - traduccion - Mejores prácticas para comentarios sobre el código de compromiso

source control traduccion (11)

¿Qué plantilla usas para los comentarios en el código de confirmación?

Un ejemplo de una plantilla es:

(cambio 1): (archivo fuente 1.1, 1.2): (detalles del cambio realizado), (por qué)
(cambio 2): (archivo fuente 2.1): (detalles del cambio realizado), (por qué)

Idealmente, cada cambio debería asignarse a un problema en el rastreador de problemas. ¿Esta plantilla está bien?

Aquí están mis pensamientos ... todo esto estará abierto a la interpretación en función de sus metodologías de desarrollo particulares.

Debe comprometerse con bastante frecuencia, con un único enfoque para cada confirmación, por lo que, en base a eso, los comentarios deben ser breves y detallados sobre cuál fue el enfoque de la confirmación.
Soy un fan de publicar lo que en su comentario, con el por qué y cómo se detalla en otra parte (idealmente en su seguimiento de errores). El por qué debería ser el boleto, y al cerrar el boleto, debe tener algún tipo de nota sobre cómo se abordó ese problema en particular.
Una referencia a su sistema de seguimiento de errores es buena si no se maneja de otra manera (interacción TRAC / SVN, por ejemplo). La razón de esto es apuntar a otros desarrolladores en la dirección correcta si están buscando más información sobre el compromiso.
No incluya nombres de archivos específicos a menos que la solución sea realmente compleja y se necesiten detalles. Aun así, los detalles complejos probablemente pertenecen al seguimiento de errores con sus notas de implementación, no al control de versiones. Los archivos editados, los detalles de diferencias, etc., deberían incluirse con el control de versión, y no queremos perder tiempo duplicando esto.

Teniendo en cuenta estas ideas, un ejemplo de comentario para mí sería algo así como

Req3845: validación actualizada para usar la nueva validación RegEx desarrollada en Req3831.

Corto, comunica lo que se cambió y proporciona algún tipo de referencia para que otros obtengan más información sin perseguirte.

Esto es lo que he visto usado con éxito:

Referencia al número de error o ID de función
Breve descripción del cambio. Lo que se cambió.
Revisor de código (para asegurarse de que tiene uno) a menos que sea manejado por el sistema de registro.
Nombre del probador o descripción de las pruebas que se ejecutaron (si se encuentra al final del proceso y tiene mucho cuidado)

Intento mantener mis arreglos en check-ins separados.

No uso una plantilla real, sino mental, y es así.

Problema: resumen del nivel de desarrollo del problema.

El rastreador de problemas tiene todos los detalles de administración, y los cambios / diferencias se pueden revisar en busca de cambios en el código, por lo que el comentario es para que los desarrolladores entiendan el por qué y el problema.

Intento seguir la misma regla que para los comentarios de código:

Explica el POR QUÉ , no el CÓMO .

En mi opinión, un comentario debe contener una referencia al problema (rastreador de tareas o requisito). Los archivos afectados ya están disponibles en el sistema de control de versiones. Aparte de eso, debe ser lo más corto posible, pero todavía legible.

No hay una regla dura y rápida como su inglés simple. Intento explicar el trabajo realizado en el mínimo posible de palabras. Cualquiera que busque un historial de cambios solo quiere saber qué sucedió en un cambio en particular. Si alguien está buscando más detalles, entonces está en el código.

La segunda cosa que sigo es que si hay algún error asociado, guárdelo o si está relacionado con alguna tarea de desarrollo, entonces asocie eso con el cambio.

Prefijo cada párrafo con + - * o!

+ means its a new feature - means feature is removed * means feature is changed ! means bugfix

No creo que debas hacer una descripción detallada sobre qué partes del código se han cambiado, porque es por eso que cada VC tiene diferencias :)

Primero, las confirmaciones deben resolver un solo problema (confirmaciones separadas para cambios separados lógicamente). Si no sabe qué escribir en el mensaje de confirmación, o si el mensaje de compromiso es demasiado largo, puede significar que tiene múltiples cambios independientes en su confirmación y debe dividirlo en elementos más pequeños.

Creo que las convenciones de mensajes de confirmación esperadas y utilizadas por git tienen mucho sentido:

La primera línea del mensaje de confirmación debe ser una breve descripción.
Si corresponde, prefijo la línea de resumen mencionada anteriormente con el prefijo del subsistema, por ejemplo, "docs:" o "contrib:"
En el siguiente párrafo o párrafos describen el cambio, explicando por qué y cómo

Si se cambiaron dos archivos por diferentes motivos, deberían estar en confirmaciones diferentes La única vez que debe confirmar más de un archivo de código a la vez es porque todos pertenecen a la misma solución / cambio

Si utiliza un sistema de seguimiento de errores, incluya los números de tickets relevantes.

No necesita mencionar los archivos modificados, o su nombre. El repositorio de origen puede darse cuenta de eso por sí mismo. Describir los cambios también tiene sentido si no es obvio desde el punto de vista no trivial.

Asegúrese de tener una buena primera línea, ya que esto aparece con frecuencia en la vista del historial de cambios, y la gente necesita encontrarlo (por ejemplo, el número del ticket de seguimiento de fallos debería ir allí).

Intente confirmar los cambios relacionados en un único conjunto de cambios (y divida los cambios no relacionados en dos confirmaciones, incluso si se trata del mismo archivo).

Tenga en cuenta que si alguien necesita detalles de lo que cambió, puede obtener una diferencia. Dicho esto, normalmente escribo una o dos oraciones por cada cambio importante, y luego agrupo cualquier corrección menor al final.

Uso la técnica simple descrita por Chaosben en el blog JEDI Windows API .

Para obtener una vista rápida de los cambios realizados en un repositorio, sugerimos escribir comentarios breves y concisos que comiencen cada línea con uno de estos caracteres:
+ si has añadido una característica / función / ...
- Si has eliminado una característica / función / error / ...
# si has cambiado algo
Haciéndolo de esta manera, otros desarrolladores pueden encontrar la revisión deseada mucho mejor.