version-control - tipos - github
Mejores prácticas para los comentarios de control de versión (10)
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 registro a menudo, también debe incluir TO DO para que uno de sus compañeros de trabajo pueda completar la tarea.
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://redbitbluebit.com/subversion-check-in-comment-great-practices/
Como el chico que está preparando las notas de la versión, estoy buscando formas 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 función tiene un ticket / issue / bugreport / task / whatever-you-call-it, y el número de ticket siempre se referencia en el comentario de check-in. Esto da contexto.
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.
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, 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 registro 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.
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 registros 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 preferencia personal es este estilo:
ACTUALIZADO el sistema de registro de errores.
- Se agregó una rutina de análisis de errores heredados usando regex para obtener los códigos de error heredados.
- Cambió el texto en los mensajes de error de la base de datos para corregir errores ortográficos.
- 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 incluir 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.
Yo diría que intenté 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 como Trac o integración de resumen + svn, puede seleccionar los números de emisión de los mensajes de confirmación. Siempre pondría estos en la primera línea ya que son muy útiles.
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 compromiso que ya se encuentra en un documento de requisitos o en un sistema de problemas / defectos.
Puede utilizar una herramienta para recopilar los números de soluciones / problemas relevantes que se encuentran en los comentarios de compromiso y luego recopilarlos de su otro repositorio, pero creo que es un error básicamente hacer que su herramienta de revisión sea externa.
Debe definir qué es el repositorio de origen / versión / SVN: si se trata de la gestión de sus archivos de origen o si también es para escribir una nota de lanzamiento. Creo que no debería estar sobrecargado
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 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.
Con respecto a las notas de la versión, hemos encontrado que trabajar con la lista 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 mensajes de compromiso sin formato, ya que a sus clientes realmente no les importan 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.
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 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ía 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. 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.