Mi commit de Git favorito (2019)

Mi commit de Git favorito

• Se enfatiza la importancia de los mensajes de commit de Git, y se considera que son una de las herramientas más poderosas para documentar una base de código.
• Se explica por qué usando como ejemplo un commit escrito por el desarrollador Dan Carley titulado "Convert template to US-ASCII to fix error".
• Con base en la experiencia en GDS (Government Digital Service), se señala que una de las ventajas de programar en público es que estos ejemplos también pueden compartirse fuera de la organización.

Por qué este commit es bueno

• La proporción entre el mensaje del commit y los cambios en el código es curiosa, pero esa no es la razón por la que se considera valioso compartirlo.
• En otra organización o por parte de otro desarrollador, este mensaje de commit podría haberse resumido simplemente como change whitespace o fix bug.
• En cambio, Dan dedicó tiempo a crear un mensaje de commit realmente útil para quienes lo rodean.

Explica la razón del cambio

• Los mejores mensajes de commit explican no solo qué se cambió, sino también por qué se cambió.
• En este commit, se detalla por qué la prueba introducida para hacer coincidir el contenido de /etc/nginx/router_routes.conf fallaba con el error ArgumentError: invalid byte sequence in US-ASCII al ejecutarse con bundle exec rake.
• Este tipo de información es muy valiosa para documentar, y puede perderse fácilmente cuando la gente olvida el contexto original o cambia de equipo y deja la organización.

Es fácil de buscar

• La primera parte del mensaje de commit contiene el mensaje de error que provocó el cambio, por lo que cualquiera puede buscar ese error en la base de código ejecutando git log --grep "invalid byte sequence" o usando la búsqueda de commits de GitHub.
• De hecho, varias personas pudieron buscar este problema y averiguar quién lo había encontrado antes y cómo lo había abordado.

Cuenta una historia

• El mensaje de commit contiene detalles sobre cómo se veía el problema, cómo fue el proceso de investigación y cómo se resolvió.
• Los mensajes de commit no son solo adecuados para documentar archivos, funciones o líneas de código específicas, sino que también son excelentes para documentar información adicional sobre el recorrido que ha vivido la base de código.

Hace que todos sean un poco más inteligentes

• El hecho de que Dan documentara los comandos que ejecutó en cada etapa puede ser una forma ligera de compartir conocimiento dentro del equipo.
• Al leer este mensaje de commit, alguien puede aprender algunos consejos útiles sobre el conjunto de herramientas de Unix.
• Tanto quien revise este cambio como quien encuentre este commit más adelante puede aprender esas cosas.

Construye empatía y confianza

• El último párrafo agrega un contexto humano.
• Al leerlo, puedes sentir la frustración de Dan por haber pasado una hora rastreando un bug escurridizo, así como la satisfacción de haberlo resuelto.
• Este tipo de mensajes de commit ayuda a recordar que detrás de cada cambio hay una persona que tomó la mejor decisión posible.

La importancia de un buen commit

• Este ejemplo es un caso extremo, y no se espera que todos los commits tengan este nivel de detalle.
• Sin embargo, es un gran ejemplo de cómo explicar el contexto detrás de un cambio, ayudar a que otros aprendan y contribuir al modelo mental colectivo del equipo sobre la base de código.
• Si quieres saber más sobre los beneficios de los buenos mensajes de commit y sobre herramientas que ayudan a estructurarlos con mayor facilidad, se recomiendan "Telling stories through your commits" de Joel Chippindale y "A branch in time" de Tekin Süleyman.

Opinión de GN⁺

• Este artículo destaca la importancia de los mensajes de commit de Git y muestra lo poderosos que pueden ser como herramienta para documentar la historia de una base de código y compartir conocimiento.
• El mensaje de commit de Dan Carley presenta un caso ejemplar en varios aspectos, como la razón del cambio, la facilidad de búsqueda, la narrativa, el intercambio de conocimiento y la construcción de empatía y confianza.
• Al comprender y poner en práctica la importancia de escribir buenos mensajes de commit, los desarrolladores pueden experimentar una mejor colaboración y mantenimiento del código, lo que puede contribuir a mejorar la productividad y eficiencia de todo el equipo.

[GN⁺]

Opiniones en Hacker News

• Opinión del cofundador de GitHub:

  • Los mensajes de commit de Git son una forma única de documentar código, pero no están optimizados.
  • La mayoría de las herramientas solo muestran la primera línea del mensaje de commit.
  • Git diseñó los mensajes de commit para que todos los participantes del proyecto pudieran leerlos, como si fueran el cuerpo de un correo, pero en la práctica casi no se ven.
  • También es difícil encontrar el mensaje de commit relacionado usando git blame.
  • Los mensajes de commit del proyecto Git son muy detallados, pero en realidad casi no se aprovechan.
  • Escribir una gran documentación mediante Git es, en la mayoría de las comunidades, casi una pérdida de tiempo.

• Importancia de los mensajes de commit para problemas específicos:

  • Es importante que la primera línea del mensaje de commit explique claramente el problema.
  • Si hace falta, se puede leer el resto para obtener información adicional.

• Sentimientos personales sobre los mensajes de commit:

  • Hay cierto orgullo en escribir excelentes mensajes de commit, pero no está claro si realmente aportan valor a otras personas.
  • La mayoría casi nunca busca mensajes de commit.
  • Los mensajes de commit bonitos pueden ser vanidad de programador y no tener mucho valor práctico.

• Estrategia para escribir la primera línea del mensaje de commit:

  • Al usar git log, la primera línea es lo más importante.
  • La primera línea debe indicar no qué se hizo, sino por qué se hizo.
  • Conviene escribirlo como una noticia: primero la información más importante y luego los detalles.

• Dificultad para modificar mensajes de commit:

  • Los mensajes de commit son difíciles de corregir después de escribirlos.
  • Documentos como archivos .md, wikis o Confluence se pueden editar fácilmente.
  • Conviene resistir la tentación de explicar el diseño de un componente ahí y, si hace falta, mejorar la documentación.

• Importancia de explicaciones detalladas en commits pequeños:

  • Cuanto más pequeño es el commit, más probable es que necesite una explicación relativamente larga.
  • Es importante detallar bien las razones de los cambios pequeños.

• Limitaciones de los mensajes de commit y problemas de las herramientas:

  • Hace falta que la primera línea del mensaje de commit sea más específica.
  • El resto de la explicación larga puede no tener mucho valor.
  • También se señalan problemas en las herramientas de desarrollo y la necesidad de que los mensajes de error sean más claros.
  • Se cuestiona por qué las herramientas de edición de código permiten caracteres de espacio en blanco no estándar.

• Importancia de la higiene de commits por encima del mensaje de commit:

  • Más que el nivel de detalle del mensaje de commit, importa tener una buena higiene de commits.
  • Los commits limpios e independientes facilitan extraer y reutilizar funcionalidades del código.

• Críticas al autosquash y al rebase:

  • El autosquash dificulta escribir mensajes de commit con significado.
  • El rebase debería usarse para ordenar el trabajo de forma intencional, no convertirse en el patrón por defecto al hacer merge.