version-control - ventas - perfil profesional de un contador para hoja de vida
Sugerencias para un buen mensaje de compromiso: formato/guía? (14)
Algunas reglas que trato de seguir:
- La primera línea de la descripción es un breve resumen del cambio. Muchos sistemas de control de origen le permiten ver una lista de cambios que muestran esta línea, por lo que le da un resumen aproximado.
- Incluye identificación de error y título de error. ¡No hagas que la gente lo busque!
- Haga que el Bug ID sea una URL para abrir el error, si el seguimiento de errores lo admite.
- Di lo que has cambiado
- Di por qué hiciste este cambio, en lugar de tomar otro enfoque.
- Sé muy detallado .
- Hacer que cada cambio sea pequeño hace que sea más fácil seguir el historial, y además es más fácil escribir y leer una buena descripción de compromiso.
- Cuando un cambio es estrictamente una refactorización, comienzo la primera línea con
REFACTORING:Esto me permite ignorar ese cambio cuando busco un cambio funcional deliberado. (Por supuesto, los cambios funcionales accidentales, también conocidos como errores, pueden estar en estos).
Para ver un ejemplo de un mensaje de compromiso altamente detallado, mira esta publicación de blog de mi viejo amigo Cyrus.
Estoy al comienzo de un nuevo proyecto, y estoy tratando de configurar el repositorio de manera inteligente y establecer algunas pautas de estilo de código para que todos puedan concentrarse en el código.
La mayor parte está hecha, pero todavía no estoy seguro del formato que debo aplicar para los mensajes de confirmación. Estoy totalmente a favor de la libertad y simplemente le digo a la gente que los haga claros y exhaustivos, pero he dicho que rara vez funciona, las personas tienen nociones muy diferentes de "claro" :).
Y hasta ahora, nunca he encontrado un esquema satisfactorio. Lo que hago más a menudo es: un resumen de una línea del compromiso, luego viñetas que describen cada cambio con más detalle.
Pero a menudo es un poco difícil decidir qué es lo que merece un punto y qué no, y algún tipo de clasificación, por características, archivo o cambios menores / importantes, parece apropiado. Tristemente, cada vez que trato de hacer eso, termino escribiendo mensajes de compromiso estúpidamente largos para cambios triviales ...
¿Cómo lo haces?
Considere seguir las pautas que git sigue a continuación: http://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches?id=HEAD
En particular:
(2) Describa bien sus cambios.
La primera línea del mensaje de compromiso debe ser una breve descripción (50 caracteres es el límite suave, ver DISCUSIÓN en git-commit (1)), y debe omitir el punto. También es convencional en la mayoría de los casos prefijar la primera línea con "área:" donde el área es un nombre de archivo o identificador para el área general del código que se está modificando, por ej.
. archivo: suma de comprobación de encabezado ustar se calcula sin firmar
. git-cherry-pick.txt: aclarar el uso de la notación de rango de revisión
Si tiene dudas sobre qué identificador usar, ejecute "git log - no-merges" en los archivos que está modificando para ver las convenciones actuales.
El cuerpo debe proporcionar un mensaje de compromiso significativo, que:
. explica el problema que el cambio intenta resolver, por ejemplo, qué está mal con el código actual sin el cambio.
. justifica la forma en que el cambio resuelve el problema, por ejemplo, por qué el resultado con el cambio es mejor.
. soluciones alternativas consideradas pero descartadas, si las hay.
Describe los cambios en el estado de ánimo imperativo, por ejemplo, "haz xyzzy do frotz" en lugar de "[Este parche] hace xyzzy do frotz" o "[I] cambié xyzzy para hacer frotz", como si estuvieras dando órdenes al código para cambiar su comportamiento. Intenta asegurarte de que tu explicación pueda entenderse sin recursos externos. En lugar de dar una URL a un archivo de la lista de correo, resuma los puntos relevantes de la discusión.
Cuando depende de mí, dejo el cuerpo en blanco si la primera línea del mensaje de compromiso parece explicarse por sí misma.
Creo que debes confiar en que la gente realmente pueda pensar por sí misma. Puede proporcionar algunas pautas básicas, como las que describió, pero al final las personas deben comprenderlas para poder seguirlas.
Aquí hay un extracto de mis mejores prácticas recomendadas para el control de versiones :
Siempre escriba un comentario al enviar algo al repositorio. Su comentario debe ser breve y al grano, describiendo qué fue cambiado y posiblemente por qué. Si realizó varios cambios, escriba una línea o frase sobre cada parte. Si se encuentra escribiendo una larga lista de cambios, considere dividir su compromiso en partes más pequeñas, como se describió anteriormente. Prefijar sus comentarios con identificadores como Fix o Add es una buena manera de indicar qué tipo de cambio hizo. También hace que sea más fácil filtrar el contenido más tarde, ya sea visualmente, por un lector humano, o automáticamente, por un programa.
Si corrigió un error específico o implementó una solicitud de cambio específica, también recomiendo hacer referencia al error o número de problema en el mensaje de confirmación. Algunas herramientas pueden procesar esta información y generar un enlace a la página correspondiente en un sistema de seguimiento de errores o actualizar automáticamente el problema en función de la confirmación.
Aquí hay algunos ejemplos de buenos mensajes de compromiso:
Changed paragraph separation from indentation to vertical space. ... Fix: Extra image removed. Fix: CSS patched to give better results when embedded in javadoc. Add: A javadoc {@link} tag in the lyx, just to show it''s possible. ... - Moved third party projects to ext folder. - Added lib folder for binary library files. ... Fix: Fixed bug #1938. Add: Implemented change request #39381.
En mi experiencia, tienes que hacer un seguimiento de las personas y darles instrucciones cuando no sigan las reglas de compromiso. Por supuesto, podría implementar una secuencia de comandos para aplicar algunas de las reglas (como el prefijo y la referencia a errores), pero eso no atrapará a las personas perezosas que no se molestan en escribir nada significativo. Creo que es importante explicar por qué quieres estas convenciones y cómo beneficiarán al equipo de desarrollo.
Configurar una lista de correo electrónico de compromiso y supervisarlo en busca de un mensaje es una buena forma de hacer un seguimiento de lo que las personas están haciendo. Cada vez que alguien está cometiendo algo sin un mensaje satisfactorio, lo sabrá y podrá decirles. Supongo que es lo mismo que con las convenciones de codificación, para que tengan éxito, alguien tiene que darles seguimiento.
Creo que la identificación de error (si hay una) es una buena idea.
Una de mis características favoritas sobre FogBugz es que puede configurar un script de gancho para que, cuando ingrese la identificación del error en el registro de confirmación, la información de confirmación se agregue al caso de FogBugz.
Imagen de aquí
Más allá de eso, solo escribe algo significativo sobre por qué hiciste los cambios que hiciste.
Encuentro bastante difícil lograr que los mensajes de confirmación sean correctos. ¿Por qué no proponer esto?
Cada mensaje de confirmación debe comenzar con la identificación de error / tarea que se resuelve mediante la confirmación. Cualquier otra cosa es solo charla ...
Estoy tratando de seguir estas reglas:
- Sé conciso
- Describe por qué lo haces, no lo que haces
El formato habitual para mis mensajes de confirmación es:
Issue: #[issue number] [short description]
Si tiene algún tipo de sistema de seguimiento de errores, proporcione el número de problema en el mensaje de confirmación.
Descubrí que muchos desarrolladores solo escriben algo como "Se agregó X. Removed Y", pero puedo encontrar esta información mirando el código de diferencia. Si no hay un número de problema adjunto, puede ser difícil saber por qué el desarrollador realizó algún cambio.
Me gusta mucho el formato promovido por angular.js :
Pautas de compromiso de Git
Tenemos reglas muy precisas sobre cómo se pueden formatear nuestros mensajes de cometer git. Esto lleva a mensajes más legibles que son fáciles de seguir cuando se mira el historial del proyecto . Pero también utilizamos los mensajes de git commit para generar el registro de cambios de AngularJS .
Formato de mensaje de confirmación Cada mensaje de confirmación consta de un encabezado , un cuerpo y un pie de página . El encabezado tiene un formato especial que incluye un tipo , un alcance y un tema :
<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>¡Cualquier línea del mensaje de compromiso no puede tener más de 100 caracteres! Esto permite que el mensaje sea más fácil de leer en github y en varias herramientas de git.
Tipo Debe ser uno de los siguientes:
- hazaña : una nueva característica
- corregir : una corrección de errores
- documentos : la documentación solo cambia
- estilo : cambios que no afectan el significado del código (espacio en blanco, formateo, punto y coma, etc.)
- refactor : un cambio de código que ni corrige un error ni agrega una característica
- perf : un cambio de código que mejora el rendimiento
- prueba : agregar pruebas faltantes
- tarea : cambios en el proceso de compilación o herramientas auxiliares y bibliotecas, como la generación de documentación
Ámbito El alcance podría ser cualquier cosa que especifique el lugar del cambio de compromiso. Por ejemplo,
$location,$browser,$compile,$rootScope,
ngHref,ngClick,ngView, etc ...Sujeto El tema contiene una descripción sucinta del cambio:
- use el imperativo, tiempo presente: "cambio" no "cambiado" ni "cambios"
- no escribas en mayúscula la primera letra
- sin punto (.) al final
Cuerpo Al igual que en el sujeto , use el imperativo tiempo presente: "cambio" no "cambiado" ni "cambios" El cuerpo debe incluir el
motivación para el cambio y contraste esto con el comportamiento anterior.
Footer El pie de página debe contener cualquier información acerca de Breaking Changes y también es el lugar para hacer referencia a los problemas de GitHub que este
comprometerse cierra
Una descripción detallada está disponible aquí .
Ejemplo:
fix (ngOptions): ngModel es opcional
Mi formato de mensaje de compromiso preferido se basa en Cómo escribir un mensaje de compromiso de Chris Beams, junto con los "verbos activos" de Joel Parker Henderson , y algunas de mis propias ideas:
- Conducir con la identificación del problema. Esto hace que sea fácil ver el número de caso relevante sin necesidad de buscar el cuerpo del mensaje de confirmación.
- Explique que el problema se resuelve desde la perspectiva del usuario final (si corresponde). Esta parte debe ser una descripción general no técnica, concisa y de alto nivel. Esto puede duplicar el contenido en el sistema de seguimiento de problemas, pero eso está bien. Al revisar el historial de confirmaciones, no quiero tener que abrir un problema en el sistema de seguimiento para comprender los conceptos básicos de cada confirmación.
- ¿Qué lo causó desde una perspectiva de desarrollo? ¿Alguien accidentalmente introdujo una mala lógica al copiar / pegar? Revisa el historial de confirmaciones para ver qué sucedió. Si simplemente no sabes qué lo causó, está bien, escribe: "No sé por qué esto se rompió". Al menos, el próximo desarrollador sabrá que solo estaba adivinando.
- Por qué este cambio lo soluciona ¿Por qué el nuevo código es más correcto que el código anterior? Si no pudo determinar por qué el código anterior era incorrecto, ¿qué le hace pensar que el nuevo código es correcto?
Formato:
IssueID: Short description (starting with one of the "active verbs")
Concise overview of problem (ideally from the end-user perspective).
Caused by (technical reasons go here).
Fixed by (technical fix explanation goes here).
Ejemplo:
995: Fix JS error on landing page preventing sign-in
It wasn''t possible to sign in on the landing page because the email and
password inputs were not being displayed.
Caused by invalid logic accidentally introduced by #994 which assumed
that the user was already signed in, thus attempting to render the
welcome message with the user''s name (which isn''t yet accessible since
they''re not signed in).
Fixed by changing the logic to check if the user is already signed in
before attempting to render the welcome message.
En el ejemplo anterior, debería ser capaz de decir cuál fue el problema, cómo se comportó de esa manera y por qué creo que estos cambios son la manera correcta de solucionar el problema. Ni siquiera debería necesitar ver el código para comprender qué se cambió y por qué.
Para cambios triviales, está perfectamente bien omitir el cuerpo de compromiso (e incluso el número de problema, si el cambio no está relacionado con ningún problema rastreado).
Ejemplos:
Cut old dead code
Document User.setAddress
Refactor User.getName for readability
564: Add missing name to profile page
Bump lodash to latest version
Mis 5 centavos, el siguiente enlace es para git, pero de todos modos, podría ser útil:
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Lo básico (de acuerdo con ese artículo) es escribir primero una breve descripción (50 caracteres) y luego puedes detallar más cosas, quedándote siempre con menos de 72 caracteres de ancho.
Prefijamos cada línea de comentario con un símbolo + o - para indicar si debe incluirse en una lista de cambios de lanzamiento. La lista de cambios (o al menos un primer borrador) se puede generar automáticamente desde nuestro registro de control de revisiones.
Más allá de eso, tenemos una palabra clave (elegida de un conjunto finito) para indicar el tipo de confirmación (corrección de errores, nueva función, limpieza, etc.), y luego un comentario breve que describe el cambio, con enlaces a nuestro sistema de seguimiento de problemas.
[+/-][Keyword]: [Description]
El formato general se puede aplicar con un enlace de confirmación, pero las descripciones aún deben ser verificadas por el ser humano para asegurarse de que todos estén haciendo mensajes de confirmación útiles.
Realmente no nos importa el texto libre, pero se requiere que todos ingresen la identificación del ticket de seguimiento de fallas de la tarea a la que pertenece el commit y que revise el código por pares.
El primero puede generar un poco de sobrecarga para soluciones rápidas, pero puede ser un salvavidas. Tener la razón real de cada línea de código a la mano es muy valioso.
El segundo solo anima a hacer revisiones por pares.
Una cosa que siempre hago es esto: si el cambio se desencadena por algún tipo de error / rastreador de software, entonces incluya la identificación del error de una manera consistente. De esta forma, es más fácil seguir todos los cambios relacionados con un error en una etapa posterior.
Ejemplo:
ID de error: 2345 Se agregó validación de la entrada del usuario para evitar la explotación.
Usamos Altassian JIRA como un rastreador de errores, y Subversion para nuestro control de fuente: JIRA tiene una buena característica en la que puede rastrear las confirmaciones relacionadas con ese error y ponerlo en el historial de resolución de errores.
Como tal, el formato que usualmente tomamos es:
PROJECTCODE - 1234: descripción detallada de los cambios realizados
Al decir "razonablemente detallado" lo que quiero decir es que no solo pones "error fijo" o "cambio de implementación", usualmente pones una descripción que no es muy específica, el error aún dice lo que realmente se hizo, por ejemplo, "estrategia de clasificación" para SortingMethod () se cambió de sortija de burbuja a quicksort para mejorar el rendimiento ".
- ID de error: (si corresponde)
- Cambiar descripción:
- Código revisado por:
- Unidad probada:
- Etiqueta de lanzamiento objetivo: