Mensajes de confirmación de Git: formato 50/72

Tim Pope argumenta a favor de un estilo particular de mensaje de compromiso de Git en su publicación de blog: http://www.tpope.net/node/106 .

Aquí hay un resumen rápido de lo que recomienda:

• La primera línea tiene 50 caracteres o menos.
• Luego una línea en blanco.
• El texto restante debe estar envuelto en 72 caracteres.

Su publicación en el blog explica las razones de estas recomendaciones (a las que llamaré “formato 50/72” por brevedad):

• En la práctica, algunas herramientas tratan la primera línea como una línea de asunto y el segundo párrafo como un cuerpo (similar al correo electrónico).
• git log no maneja la envoltura, por lo que es difícil de leer si las líneas son demasiado largas.
• git format-patch --stdout convierte los commits en correo electrónico, por lo que jugar bien ayuda si tus commits ya están bien envueltos.

Un punto que me gustaría agregar que creo que Tim estaría de acuerdo con:

• El acto de resumir su confirmación es una buena práctica inherente a cualquier sistema de control de versiones. Ayuda a otros (o más tarde a usted) a encontrar compromisos relevantes más rápidamente.

Entonces, tengo un par de ángulos para mi pregunta:

• ¿Qué parte (aproximadamente) de los "líderes de pensamiento" o "usuarios experimentados" de Git adoptan el estilo de formato 50/72? Pregunto esto porque en algún momento los nuevos usuarios no conocen o no les importan las prácticas de la comunidad.
• Para aquellos que no usan este formato, ¿hay alguna razón de principios para usar un estilo de formato diferente? (Tenga en cuenta que estoy buscando un argumento sobre los méritos, no "Nunca he oído hablar de él" o "No me importa").
• Hablando empíricamente, ¿qué porcentaje de repositorios de Git adopta este estilo? (En caso de que alguien quiera hacer un análisis de los repositorios de GitHub ... pista, pista).

Mi punto aquí no es recomendar el estilo 50/72 o derribar otros estilos. (Para ser abierto al respecto, lo prefiero, pero estoy abierto a otras ideas). Solo quiero obtener la justificación de por qué a la gente le gusta o se opone a varios estilos de mensajes de compromiso de Git. (Siéntase libre de mencionar puntos que no se han mencionado también).

Con respecto a la línea de "resumen" (los 50 en su fórmula), la documentación del kernel de Linux tiene esto que decir :

For these reasons, the "summary" must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary.  It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.

Dicho esto, parece que los mantenedores del núcleo intentan mantener las cosas alrededor de 50. Aquí hay un histograma de las longitudes de las líneas de resumen en el registro git para el núcleo:

( ver en tamaño completo )

Hay un puñado de confirmaciones que tienen líneas de resumen que son más largas (algunas mucho más largas) de las que puede contener este gráfico sin hacer que la parte interesante parezca una sola línea. (Probablemente haya alguna técnica estadística sofisticada para incorporar esos datos aquí, pero bueno ... :-)

Si quieres ver las longitudes en bruto:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{print length($0)}'

o un histograma basado en texto:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }' | sort -n

Con respecto a los "líderes de opinión": Linus defiende enfáticamente el ajuste de línea para el mensaje de compromiso completo:

[…] Usamos columnas de 72 caracteres para el ajuste de palabras, excepto para el material citado que tiene un formato de línea específico.

Las excepciones se refieren principalmente al texto "no en prosa", es decir, texto que no fue escrito por un humano para la confirmación, por ejemplo, mensajes de error del compilador.

La separación de presentación y datos impulsa mis mensajes de confirmación aquí.

Su mensaje de confirmación no debe estar envuelto en ningún recuento de caracteres y, en su lugar, los saltos de línea deben usarse para separar pensamientos, párrafos, etc., como parte de los datos, no la presentación. En este caso, los "datos" son el mensaje que está tratando de transmitir y la "presentación" es cómo el usuario lo ve.

Utilizo una sola línea de resumen en la parte superior e intento mantenerla corta pero no me limito a un número arbitrario. Sería mucho mejor si Git realmente proporcionara una forma de almacenar mensajes de resumen como una entidad separada del mensaje, pero dado que no es así, tengo que hackear uno y uso el primer salto de línea como delimitador (afortunadamente, muchas herramientas admiten esto significa separar los datos).

Para el mensaje en sí, las nuevas líneas indican algo significativo en los datos. Una nueva línea nueva indica un inicio / interrupción en una lista y una nueva línea nueva indica un nuevo pensamiento / idea.

This is a summary line, try to keep it short and end with a line break.
This is a thought, perhaps an explanation of what I have done in human readable format.  It may be complex and long consisting of several sentences that describe my work in essay format.  It is not up to me to decide now (at author time) how the user is going to consume this data.

Two line breaks separate these two thoughts.  The user may be reading this on a phone or a wide screen monitor.  Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across?  It is a truly painful experience.  Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph.  Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else's throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

Así es como se ve en un visor que envuelve suavemente el texto.

Esta es una línea de resumen, intente que sea corta y termine con un salto de línea.

Este es un pensamiento, quizás una explicación de lo que he hecho en formato legible para humanos. Puede ser complejo y largo que consiste en varias oraciones que describen mi trabajo en formato de ensayo. No depende de mí decidir ahora (en el momento del autor) cómo el usuario va a consumir estos datos.

Dos saltos de línea separan estos dos pensamientos. El usuario puede estar leyendo esto en un teléfono o en un monitor de pantalla ancha. ¿Alguna vez ha intentado leer texto envuelto de 72 caracteres en un dispositivo que solo muestra 60 caracteres? Es una experiencia realmente dolorosa. Además, la oración de apertura de este párrafo (asumiendo el formato de estilo de ensayo) debe ser una introducción al párrafo, por lo que si una herramienta elige no querrá autoenvolverse y dejarle ver el comienzo de cada párrafo. Una vez más, depende de la herramienta de presentación, no de mí (un autor aleatorio en algún momento de la historia) tratar de forzar mi formato particular a todos los demás.

Solo como ejemplo, aquí hay una lista de puntos:
* Punto 1.
* Punto 2.
* Punto 3.

Sospecho que el autor de la recomendación de mensaje de compromiso de Git que ha vinculado nunca ha escrito software que antes sea consumido por una amplia gama de usuarios finales en diferentes dispositivos (es decir, un sitio web) desde este momento en la evolución del software / informática es bien sabido que almacenar sus datos con información de presentación codificada es una mala idea en lo que respecta a la experiencia del usuario.

Estoy de acuerdo en que es interesante proponer un estilo particular de trabajo. Sin embargo, a menos que tenga la oportunidad de establecer el estilo, generalmente sigo lo que se ha hecho para mantener la coherencia.

Echando un vistazo a Linux Kernel Commits, el proyecto que comenzó git si lo desea, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , no siguen la regla 50/72. La primera línea tiene 54 caracteres.

Yo diría que la consistencia importa. Configure los medios adecuados para identificar a los usuarios que han realizado confirmaciones (user.name, user.email, especialmente en redes internas. User @ OFFICE-1-PC-10293982811111 no es una dirección de contacto útil). Dependiendo del proyecto, haga que los detalles apropiados estén disponibles en la confirmación. Es difícil decir qué debería ser; pueden ser tareas completadas en un proceso de desarrollo, luego detalles de lo que ha cambiado.

No creo que los usuarios deberían usar git de una manera porque ciertas interfaces para git tratan las confirmaciones de ciertas maneras.

También debo señalar que hay otras formas de encontrar commits. Para empezar, git diffte diré qué ha cambiado. También puede hacer cosas como git log --pretty=format:'%T %cN %ce'formatear las opciones de git log.

¿La longitud máxima recomendada del título es realmente 50?

He creído esto durante años, pero como acabo de notar, la documentación de "git commit" en realidad dice

$ git help commit | grep -C 1 50
      Though not required, it’s a good idea to begin the commit message with
      a single short (less than 50 character) line summarizing the change,
      followed by a blank line and then a more thorough description. The text

$  git version
git version 2.11.0

Se podría argumentar que "menos de 50" solo puede significar "no más de 49".