Nota perev. : Esta publicación de un programador británico, que se ha convertido en un verdadero éxito en Internet de habla inglesa, hace referencia a un compromiso de Git hace 6 años. Fue grabado en uno de los repositorios abiertos del Servicio Digital del gobierno, un servicio dedicado al desarrollo de servicios digitales en el Reino Unido y que apoya el proyecto GOV.UK. El commit en sí mismo es interesante no tanto con los cambios en el código, sino con la descripción que los acompaña ...
Imagen de xkcd # 1296Me encanta cometer descripciones en Git. Cuando se usan correctamente, se les puede llamar una de las herramientas más poderosas para documentar la evolución de la base de código durante su existencia. Quiero ilustrar mi punto de vista con el ejemplo de mi descripción favorita.
Este compromiso se remonta a cuando trabajaba en Government Digital Service. Su autor es un desarrollador llamado
Dan Carley , y tiene un título bastante poco notable: "
Convirtió la plantilla a US-ASCII para corregir el error ".
“He implementado varias pruebas en la rama de características para que coincida con el contenido de` / etc / nginx / router_routes.conf`. Funcionaron bien si se ejecutan con los comandos `bundle exec rake spec` o` bundle exec rspec modules / router / spec`. Pero cuando se ejecuta `bundle exec rake`, cada bloque debería fallar:
ArgumentError: invalid byte sequence in US-ASCII
Al final, descubrí que después de la excepción a la expresión `.with_content (//)`, todos los errores desaparecen. Que no hay caracteres extraños en el archivo de especificación. Y también que se puede jugar llamando a Puppet en el mismo intérprete:
rake -E 'require "puppet"' spec
Esta plantilla parece ser el único archivo en nuestra base de código codificado con 'utf-8'. Todos los demás archivos en 'us-ascii':
dcarley-MBA:puppet dcarley$ find modules -type f -exec file --mime {} \+ | grep utf modules/router/templates/routes.conf.erb: text/plain; charset=utf-8
Un intento de transcodificarlo en US-ASCII falló debido a un solo carácter que parece un espacio:
dcarley-MBA:puppet dcarley$ iconv -f UTF8 -t US-ASCII modules/router/templates/routes.conf.erb 2>&1 | tail -n5 proxy_intercept_errors off; # Set proxy timeout to 50 seconds as a quick fix for problems # iconv: modules/router/templates/routes.conf.erb:458:3: cannot convert
Después de reemplazarlo (manualmente) el archivo nuevamente se convirtió en 'US-ASCII':
dcarley-MBA:puppet dcarley$ file --mime modules/router/templates/routes.conf.erb modules/router/templates/routes.conf.erb: text/plain; charset=us-ascii
¡Ahora las pruebas funcionan! Toda la hora de mi vida no puede ser devuelta ... "
En el originalConvierta la plantilla a US-ASCII para corregir el error
Introduje algunas pruebas en una rama de características para que coincida con el contenido de
`/ etc / nginx / router_routes.conf`. Funcionaron bien cuando se ejecutan con `bundle exec
rake spec` o `bundle exec rspec modules / router / spec`. Pero cuando corres como
`bundle exec rake` cada bloque debería fallar con:
ArgumentError: invalid byte sequence in US-ASCII
Eventualmente descubrí que eliminar los matizadores `.with_content (//)` hizo que
los errores desaparecen Que no había ningún personaje extraño en el archivo de especificaciones. Y
que podría reproducirse requiriendo Puppet en el mismo intérprete con:
rake -E 'require "puppet"' spec
Esa plantilla en particular parece ser el único archivo en nuestra base de código con un
codificación identificada de 'utf-8'. Todos los demás son `us-ascii`:
dcarley-MBA:puppet dcarley$ find modules -type f -exec file --mime {} \+ | grep utf modules/router/templates/routes.conf.erb: text/plain; charset=utf-8
Intentar convertir ese archivo de nuevo a US-ASCII identificó al infractor
personaje como algo que parecía un espacio en blanco:
dcarley-MBA:puppet dcarley$ iconv -f UTF8 -t US-ASCII modules/router/templates/routes.conf.erb 2>&1 | tail -n5 proxy_intercept_errors off; # Set proxy timeout to 50 seconds as a quick fix for problems # iconv: modules/router/templates/routes.conf.erb:458:3: cannot convert
Después de reemplazarlo (a mano) el archivo se identifica como `us-ascii` nuevamente:
dcarley-MBA:puppet dcarley$ file --mime modules/router/templates/routes.conf.erb modules/router/templates/routes.conf.erb: text/plain; charset=us-ascii
¡Ahora las pruebas funcionan! Una hora de mi vida no volveré ...
Una pequeña digresión: uno de los beneficios del
desarrollo de código abierto que se practica en GDS es que puede compartir ejemplos como este fuera de la organización que los creó. No sé quién propuso este concepto por primera vez a GDS; cuando me uní a la organización, ya se usaba ampliamente, pero estoy infinitamente agradecido con esta persona.
¿Por qué me gusta este commit?
Incontables veces lo he citado como un ejemplo de lo que son capaces las descripciones de compromiso. Es algo divertido por la proporción de cambios en el código y el tamaño de la descripción, pero no me gusta en absoluto.
En otra empresa, con otro desarrollador, todo el mensaje del compromiso podría reducirse a frases como "reemplazó el espacio", "arregló el error" o (según la cultura del equipo) a ataques contra el inventor de espacios inextricables. En cambio, Dan se tomó el tiempo para crear una descripción detallada útil para otros. Me gustaría hacer hincapié en las razones por las que considero que este compromiso es un muy buen ejemplo.
Revela la razón de los cambios.
Las mejores descripciones de commits no solo informan sobre
lo que ha cambiado, sino que también explican
por qué . En nuestro caso:
He implementado varias pruebas en la rama de características para que coincida con el contenido de `/ etc / nginx / router_routes.conf`. Funcionaron bien si se ejecutan con los comandos `bundle exec rake spec` o` bundle exec rspec modules / router / spec`. Pero cuando se ejecuta `bundle exec rake`, cada bloque debería fallar:
ArgumentError: invalid byte sequence in US-ASCII
Sin ese nivel de detalle, podríamos suponer que la confirmación corrigió el error de análisis en una herramienta en particular. Gracias a la descripción de la confirmación, sabemos qué tipo de herramienta era.
Este tipo de información puede resultar realmente valiosa, y es demasiado fácil de perder, ya que las personas tienden a olvidar las complejidades de su trabajo, mudarse a otros equipos y, en última instancia, abandonar la empresa.
Bueno para buscar
Uno de los elementos clave de esta descripción es el error en sí mismo, con el que comenzaron las búsquedas adicionales:
ArgumentError:
secuencia de bytes no válida en US-ASCII
Cualquiera que encuentre este error puede buscar la base del código, ya sea ejecutando
git log --grep "invalid byte sequence" , o usando la
búsqueda de confirmaciones de GitHub . De hecho, a juzgar por los resultados de la búsqueda, muchos ya lo han hecho y descubrieron quién y cuándo se enfrentó a este problema y cómo se resolvió finalmente.
Proporciona una imagen completa.
El mensaje de confirmación detalla cómo se veía el problema, cómo se investigó y se resolvió. Por ejemplo:
Al final, descubrí que después de la excepción a la expresión `.with_content (//)`, todos los errores desaparecen. Que no hay caracteres extraños en el archivo de especificación. Y también que se puede jugar llamando a Puppet en el mismo intérprete.
Esta es una de las áreas en las que los mensajes en las confirmaciones son realmente capaces de mostrarse, porque describen el cambio en sí, y no algún archivo, función o línea de código. Esto los convierte en un gran lugar para almacenar este tipo de información adicional de aventura de base de código.
Hace a todos un poco más inteligentes
Dan hizo una cosa aquí, que realmente aprecio: trajo todos los equipos que realicé en cada etapa. Esta es una forma excelente y asequible de compartir conocimientos en un equipo. Al leer su descripción de la confirmación, puede aprender mucho sobre las herramientas de Unix:
- puede pasar el argumento
-exec para find ejecutar un comando con cada archivo encontrado; - agregar
\+ al final del comando hace algo muy interesante (pasa varios nombres de file comando de file y no ejecuta el comando una vez para cada archivo); file --mime permite averiguar el tipo MIME del archivo;- Hay una utilidad
iconv .
Una persona que ve una descripción puede aprender sobre todas estas cosas. Cualquiera que tropiece con este compromiso más tarde también aprenderá sobre estas cosas. Si multiplica este enfoque de los compromisos durante un tiempo prolongado y una cantidad suficiente de ellos, puede convertirse en un poderoso incentivo para el equipo.
Desarrolla empatía y confianza.
¡Ahora las pruebas funcionan! Toda la hora de mi vida no puede ser devuelta ...
El último párrafo agrega un mínimo de humanidad. Al leer estas palabras, es difícil no sentir la decepción de Dan, que tuvo que pasar una hora entera buscando un error oculto y la satisfacción de corregirlo.
Ahora imagine un mensaje similar adjunto a un truco o fragmento temporal del código prototipo que entró en producción y "echó raíces" (como suele ser el caso con dichos fragmentos). Esta descripción de la confirmación recuerda a todos que detrás de cada cambio hay una persona que toma la mejor decisión posible, dada la información disponible en ese momento.
Los buenos compromisos importan
Admito que este es un ejemplo extremo, y no espero que todos los commits (especialmente de tal alcance) cuenten con el mismo nivel de detalle. Sin embargo, sigo pensando que este es un gran ejemplo para explicar la razón del cambio, ayudar a otros a aprender cosas nuevas y contribuir al modelo mental colectivo asociado con la base del código.
Si desea saber un poco más sobre las ventajas de una buena descripción de los commits y algunas herramientas que facilitan la estructuración de las ediciones, le puedo recomendar los siguientes materiales:
PD del traductor
Lea también en nuestro blog: