Git los mensajes de confirmación: 50/72 de formato

Question

Tim Papa aboga por un git confirmación en concreto del estilo del mensaje en su blog: http://www.tpope.net/node/106

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

• Primera línea es de 50 caracteres o menos
• Entonces una línea en blanco
• restante texto debe ser envuelto en 72 caracteres

Su entrada en el blog da la razón de estas recomendaciones (que llamaré "50/72 formato" por razones de brevedad):

• En la práctica, algunas herramientas de tratar a 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 el envoltorio, por lo que es difícil de leer si las líneas son demasiado largas.
• git format-patch --stdout convierte las confirmaciones al correo electrónico, por lo que, para jugar bien, resulta útil que sus confirmaciones ya estén envueltas.
• un punto que me gustaría añadir que creo que Tim estaría de acuerdo con: el acto de resumir tu compromiso 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.

lo tanto, tengo un par de piezas a mi pregunta:

• Lo trozo (más o menos) de la 'líderes de opinión' o abrazo de Git 'usuarios experimentados' el estilo de formato 50/72? Pregunto esto porque algunos usuarios más nuevos no saben o no les importan las prácticas comunitarias.
• Para aquellos que no usan este formato, ¿existe una 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 git adopta este estilo? (En caso de que alguien quiere hacer un análisis sobre los repositorios de GitHub ... indirecta, indirecta.)

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 razón de por qué las personas les gusta o se oponen a varios estilos de mensajes de error de GIT. (No dude en mencionar los puntos que no se han mencionado, también.)

Answer 1

En cuanto a la línea de "Resumen" (el 50 en la fórmula), the Linux kernel documentation has this to say:

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 kernel en efecto, tratar de mantener las cosas alrededor de 50. Aquí está un histograma de las longitudes de las líneas de resumen en el registro de git para el núcleo:

(view full-sized)

Hay un puñado de confirmaciones que tienen líneas de resumen que son más largos (algunos mucho más) de lo que esta trama puede contener 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 primas:

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 

Answer 2

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, suelo seguir lo que se ha hecho para mantener la coherencia.

Echando un vistazo a Linux Kernel Commits, el proyecto que inició 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 es de 54 caracteres.

Yo diría que la coherencia importa. Configure los medios adecuados para identificar a los usuarios que han realizado commits (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 lo que debería ser; pueden ser tareas completadas en un proceso de desarrollo, luego detalles de lo que ha cambiado.

No creo que los usuarios deban usar git de una manera porque ciertas interfaces para tratar las compilaciones de git de ciertas maneras.

También debería tener en cuenta que hay otras maneras de encontrar confirmaciones. Para empezar, git diff le dirá qué ha cambiado. También puede hacer cosas como git log --pretty=format:'%T %cN %ce' para formatear las opciones de git log.

Answer 3

En cuanto a "líderes de opinión": Linus defiende enfáticamente el ajuste de línea para el mensaje de confirmación completa :

usamos columnas de 72 caracteres para el ajuste de palabras, excepto para el material que tiene un formato de línea específica

Las excepciones se refiere principalmente a texto "no prosa", es decir, el texto que no se ha escrito por un ser humano para la confirmación - por ejemplo, mensajes de error del compilador.

Answer 4

La separación de la presentación y los datos dirigen mis mensajes de confirmación aquí.

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

Utilizo una única línea de resumen en la parte superior y trato de mantenerlo corto, 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 como no 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 sola nueva línea indica un inicio/descanso en una lista y una doble línea nueva indica una nueva idea/pensamiento.

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. 

Esto es lo que se ve en un visor que suaviza envuelve el texto.

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

Esto es un pensamiento, tal vez una explicación de lo que he hecho en formato legible para humanos. Puede ser complejo y largo y consta de varias oraciones que describen mi trabajo en formato de ensayo. No me corresponde a mí decidir ahora (en el momento del autor) cómo va a consumir el usuario esta información.

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 tratado de leer texto envuelto de 72 caracteres en un dispositivo que solo muestra 60 caracteres? Es una experiencia verdaderamente dolorosa. Además, la oración de apertura de este párrafo (suponiendo el formato del estilo del ensayo) debe ser una introducción al párrafo, de modo que si una herramienta lo elige, puede que no quiera autoenrollarlo y le permita ver el comienzo de cada párrafo. De nuevo, depende de la herramienta de presentación, no de mí (un autor aleatorio en algún momento de la historia) tratar de forzar a mi formateo particular a bajar la garganta de los demás.

Sólo como ejemplo, aquí es una lista de puntos:
* Punto 1.
* Punto 2.
* Punto 3.

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