Sugerencias para un buen post de compromiso: formatting / guía?

Estoy al comienzo de un nuevo proyecto, y estoy tratando de configurar el repository 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 formatting que debo aplicar para los posts de confirmación. Estoy totalmente a favor de la libertad y simplemente le digo a la gente que los haga claros y completos, pero tengo 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 sorting, por características, file o cambios menores / importantes, parece apropiado. Tristemente, cada vez que trato de hacer eso, termino escribiendo posts de compromiso estúpidamente largos para cambios triviales …

¿Cómo lo haces?

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 repository. 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 list 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 progtwig.

Si corrigió un error específico o implementó una request de cambio específica, también recomiendo hacer reference al error o número de problema en el post 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 function de la confirmación.

Aquí hay algunos ejemplos de buenos posts de compromiso:

  Se modificó la separación de párrafo de la sangría al espacio vertical.
 ...
 Solución: image extra eliminada.
 Corrección: CSS parcheado para get mejores resultados cuando está embedded en javadoc.
 Agregar: una label javadoc {@link} en lyx, solo para mostrar que es posible.
 ...
 - Moví proyectos de terceros a la carpeta ext.
 - Se agregó una carpeta lib para los files de la biblioteca binaria.
 ...
 Solución: error reparado # 1938.
 Agregar: Solicitud de cambio implementada # 39381. 

Según mi experiencia, debes hacer un seguimiento de las personas y darles instrucciones cuando no cumplan con las reglas de compromiso. Por supuesto, podría implementar una secuencia de commands para aplicar algunas de las reglas (como el prefijo y la reference 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 list de correo electrónico de compromiso y supervisarlo en busca de un post es una buena forma de hacer un seguimiento de lo que las personas están haciendo. Cuando alguien está cometiendo algo sin un post satisfactorio, lo sabrá y podrá decirles. Supongo que es lo mismo que con las convenciones de encoding, para que tengan éxito, alguien tiene que darles seguimiento.

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 list 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 post de compromiso altamente detallado, mira esta publicación de blog de mi viejo amigo Cyrus.

Estoy tratando de seguir estas reglas:

  1. Sé conciso
  2. Describe por qué lo haces, no lo que haces

El formatting habitual para mis posts 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 post 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 formatting promovido por angular.js :

Pautas de compromiso de Git

Tenemos reglas muy precisas sobre cómo se pueden formatear nuestros posts de cometer git. Esto lleva a posts más legibles que son fáciles de seguir cuando se mira el historial del proyecto . Pero también utilizamos los posts de git commit para generar el logging de cambios de AngularJS .

Formato de post de confirmación Cada post de confirmación consta de un encabezado , un cuerpo y un pie de página . El encabezado tiene un formatting especial que incluye un tipo , un scope y un tema :

<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>

¡Cualquier línea del post de compromiso no puede tener más de 100 caracteres! Esto permite que el post 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 documentation 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 performance
  • testing : agregar testings faltantes
  • tarea : cambios en el process de compilation o herramientas auxiliares y bibliotecas, como la generación de documentation

Ámbito El scope 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, time 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 time presente: "cambio" no "cambiado" ni "cambios" El cuerpo debe include 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 reference a los problemas de GitHub que este

comprometerse cierra

Una descripción detallada está disponible aquí .

Ejemplo:

fix (ngOptions): ngModel es opcional

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 less de 72 caracteres de ancho.

  • ID de error: (si corresponde)
  • Cambiar descripción:
  • Código revisado por:
  • Unidad probada:
  • Etiqueta de lanzamiento objective:

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ó validation de la input 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 formatting que usualmente tomamos es:

PROJECTCODE – 1234: descripción detallada de los cambios realizados

Por "razonablemente detallado" lo que quiero decir es que no se limita a poner "error fijo" o "implementación modificada", por lo general se pone una descripción que no es muy específica, el error aún dice lo que se hizo en realidad, por ejemplo, "Estrategia de sorting" para SortingMethod () se cambió de sortija de burbuja a quicksort para mejorar el performance ".

Prefijamos cada línea de comentario con un símbolo + o – para indicar si debe includese en una list de cambios de lanzamiento. La list de cambios (o al less un primer borrador) se puede generar automáticamente desde nuestro logging de control de revisiones.

Más allá de eso, tenemos una palabra key (elegida de un set finito) para indicar el tipo de confirmación (corrección de errores, nueva function, limpieza, etc.), y luego un comentario breve que describe el cambio, con enlaces a nuestro sistema de seguimiento de problemas.

 [+/-][Keyword]: [Description] 

El formatting 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 posts de confirmación útiles.

Realmente no nos importa el text 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.

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 logging de confirmación, la información de confirmación se agregue al caso de FogBugz. enter image description here

Imagen de aquí

Más allá de eso, solo escribe algo significativo sobre por qué hiciste los cambios que hiciste.

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 post 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 file o identificador para el área general del código que se está modificando, por ej.

. file: sum de comprobación de encabezado ustar se calcula sin firmar

. git-cherry-pick.txt: aclarar el uso de la notación de range de revisión

Si tiene dudas sobre qué identificador usar, ejecute "git log – no-merges" en los files que está modificando para ver las convenciones actuales.

El cuerpo debe proporcionar un post 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 resources externos. En lugar de dar una URL a un file de la list de correo, resum los puntos relevantes de la discusión.

Cuando depende de mí, dejo el cuerpo en blanco si la primera línea del post de compromiso parece explicarse por sí misma.

Encuentro bastante difícil lograr que los posts de confirmación sean correctos. ¿Por qué no proponer esto?

Cada post 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 …

Mi formatting de post de compromiso preferido se basa en Cómo escribir un post 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 search el cuerpo del post 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 copyr / 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 less, 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 forma 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