Como ya comenté anteriormente, me encuentro realizando mi tesis de grado en un tema que propone una cruza de las áreas de Big Data y Recuperación de Información. En dicho contexto, utilizo Hadoop como Framework y Java como lenguaje de desarrollo.
En dicha oportunidad prometí un post con contenido sobre desarrollo para Hadoop. Acá les dejo unas diapositivas que prepare especialmente para introducir en el tema.
Ya que estamos, si quieren mirar código y si tienen tiempo colaborar, estoy subiendo mis implementaciones a un repositorio público en Github. Es un repositorio íntegramente funcional sobre Hadoop 2. Ademas estoy tratando de ir subiendo issues para favorecer la colaboración (De alguna manera marca el estado de avance de los proyectos y da una idea de lo que falta hacer).
Si tienen intenciones de colaborar o forkear, no duden en contactarse conmigo.
Tomas en Programación |
Cómo escribir un mensaje de commit de git
Este post es una traducción del post How to Write a Git Commit Message, de @cbeams. Este trabajo se realizo en colaboración con @may_cabrera con permiso del autor original. Gracias a ambos!
Teniendo como excusa el formato y uso de comentarios en Git, el post nos muestra diversas formas de uso de este SCV, cuestiones metodológicas y de uso cotidiano de Git. Es muy interesante en muchos sentidos, así que les recomiendo tomarse un tiempo para su lectura.
Introducción | Las Siete Reglas | Consejos
Introducción: ¿Por qué es importante un buen mensaje de commit?
Si navegas el registro de un repositorio Git al azar probablemente encuentres que sus mensajes de commit son mas o menos un lío. Por ejemplo, echemos un vistazo a estas gemas de mis primeros días desarrollando para Spring:
Uff. Compara eso con estos commits más recientes del mismo repositorio:
¿Qué prefieres leer?
El primero cambia mucho en forma y tamaño; el último es conciso y consistente. El primero es lo que ocurre por defecto; el segundo nunca ocurre por accidente.
Mientras muchos logs de repositorio se ven como el primero, hay excepciones. El kernel de Linux y git en sí son grandes ejemplos. Mira Spring Boot, o cualquier repositorio gestionado por Tim Pope .
Los contribuidores de estos repositorios saben que un mensaje de commit git bien elaborado es la mejor manera de comunicar el contexto sobre un cambio al resto de los colegas desarrolladores (y ciertamente a sí mismos en el futuro). Un diff dirá lo que ha cambiado, pero sólo el mensaje de commit puede decir correctamente por qué. Peter Hutterer señala este punto así:
Si no te has puesto a pensar en como generar un buen mensaje de commit de git, puede ser que no hayas gastado suficiente tiempo usando
git log
y herramientas relacionadas. Existe un circulo vicioso aquí: Debido a que el historial de commit carece de estructura y consistencia, uno no gasta demasiado tiempo usándolo o teniéndolo en cuenta. Y debido a que no es usado o tenido en cuenta, este se mantiene sin estructura e inconsistenteSin embargo un log cuidado es algo hermoso y útil.
git blame
,revert
,rebase
,log
,shortlog
y otros subcomandos cobran vida. Revisar commits y pull requests de otros se convierte en algo digno de hacerse, y de repente se puede hacer de forma independiente. Entender porque algo sucedió hace meses o años se convierte en algo no solo posible, sino también eficiente.El éxito a largo plazo de un proyecto descansa (entre otras cosas) en su facilidad de mantenimiento, y un desarrollador tiene pocas herramientas más poderosas que el log del proyecto. Vale la pena tomarse el tiempo para aprender cómo cargarlo de una forma adecuada. Lo que puede ser una molestia en un principio pronto se convierte en hábito, y, finalmente, un motivo de orgullo y productividad para todos los involucrados.
En este artículo, me refiero sólo al elemento más básico para mantener un historial saludable de commits: cómo escribir un mensaje de commit particular. Hay otras prácticas importantes como commit squashing que no serán tratadas aquí. Tal vez lo haré en un post posterior.
La mayoría de los lenguajes de programación tienen convenciones bien establecidas de lo que conforma el estilo idiomático, es decir, de nombres y formato y cosas así. Hay variaciones en estas convenciones, por supuesto, pero la mayoría de los desarrolladores están de acuerdo en que escoger una y ajustarse a ella es mucho mejor que el caos que se produce cuando todo el mundo lo hace a su manera.
El enfoque de un equipo con su log de commits no debería ser diferente. Con el fin de crear un historial de revisiones útiles, los equipos primero deben ponerse de acuerdo sobre una convención en mensajes de commits que defina al menos las siguientes tres cosas:
Estilo. La sintaxis, los límites de márgenes, la gramática, la capitalización, la puntuación. Explica claramente estos puntos, elimina la ambigüedad y hazlo lo más claro posible. El resultado final será un log muy coherente que no sólo será fácil de leer, sino que en realidad será leído de forma regular.
Contenido. ¿Qué tipo de información debe contener el cuerpo del mensaje de commit (si lo hay)? ¿Que no debería contener?
Metadatos. ¿Cómo se debe marcar el identificador de un issue, el numero de pull request, etc. ?
Afortunadamente, hay convenciones bien establecidas sobre lo que hace a un commit un mensaje idiomático De hecho, muchas de estas convenciones se asumen como la forma determinada en ciertos comandos git. No hay nada que necesite ser reinventado. Sólo tienes que seguir las siete reglas descritas abajo y ya estarás en camino para hacer commits como un profesional.
Las siete reglas de un gran mensaje de commit de git
Por ejemplo:
1. Separa el título del cuerpo del mensaje con una linea en blanco
Desde la página de manual de
git commit
:En primer lugar, no todo commit requiere tanto un título como un cuerpo. A veces una sola línea está bien, sobre todo cuando el cambio es tan simple que agregar más contexto no es necesario. Por ejemplo:
No es necesario decir nada más; si el lector se pregunta cuál fue el error tipográfico, simplemente puede echar un vistazo al cambio, mediante el uso de
git show
ogit diff
ogit log -p
.Si estás realizando un commit de este tipo en la línea de comandos, es fácil de usar el parametro
-m
paragit commit
:Sin embargo, cuando un commit merece un poco de explicación y contexto, es necesario escribir un cuerpo. Por ejemplo:
Esto no es tan fácil de hacer con el parametro
-m
, realmente necesitas de un editor adecuado. Si aún no dispones de un editor configurado para usar con git en la línea de comandos, lee esta sección de Pro Git .En cualquier caso, la separación del titulo y cuerpo vale la pena cuando se navega por el log. Aquí está la entrada del log completo:
Y ahora
git log --oneline
, que imprime sólo la línea de título:O,
git shortlog
, que agrupa commits por usuario, de nuevo mostrando sólo la línea de titulo para ser conciso:Hay numerosos contextos en git donde la distinción entre titulo y cuerpo entran en acción, pero ninguno de ellos funciona correctamente sin la línea en blanco en el medio.
2. Limita la línea de título a 50 caracteres
50 caracteres no es un límite estricto, sólo una regla práctica. Mantener las líneas de título en esta longitud asegura que sean legibles, y obliga al autor a pensar por un momento acerca de la forma más concisa de explicar lo que está enviando.
La Interfaz de GitHub es plenamente consciente de estas convenciones. Te avisará si te pasas del límite de 50 caracteres:
Y truncará cualquier título de más de 69 caracteres con puntos suspensivos:
Así que intenta con 50 caracteres, pero considera como limite máximo 69.
3. Capitaliza la línea de título
Esto es tan simple como suena. Comienza todas las líneas de título con una letra mayúscula.
Por ejemplo:
En lugar de:
4. No termines la línea de título con un punto
Usar puntuación es innecesario en las líneas de título. Además, el espacio es muy valioso cuando se está tratando de mantener en 50 caracteres o menos .
Ejemplo:
En lugar de:
5. Utiliza el modo imperativo en la línea de título
Modo imperativo simplemente significa “hablar o escribir como si dieras una orden o instrucción”. Algunos ejemplos:
Cada una de las siete reglas que estás leyendo ahora mismo están escritas en imperativo (“Limita el cuerpo a 72 caracteres”, etc).
El imperativo puede sonar un poco grosero; es por eso que a menudo no lo usamos. Pero es perfecto para el título de un commit. Una razón para esto es que git mismo utiliza el imperativo cada vez que crea un commit con tu nombre.
Por ejemplo, el mensaje predeterminado creado al utilizar
git merge
es:Y al usar
git revert
:O cuando se hace clic en el botón “Merge” en un pull request de Github
Así que cuando escribas mensajes de commit en forma imperativa, realmente estás siguiendo las mismas convenciones incorporadas por git. Por ejemplo:
Escribir de esta manera puede ser un poco incómodo al principio. Estamos más acostumbrados a hablar en el modo indicativo, que está más relacionado para informar hechos. Es por eso que los mensajes de commits terminan leyéndose así:
Y a veces los mensajes se escriben como una descripción de su contenido:
Para eliminar cualquier confusión, aquí hay simple regla para hacerlo bien cada vez.
Un commit de git formado adecuadamente siempre debe ser capaz de completar la siguiente frase:
Por ejemplo:
Observa cómo esto no funciona para las otras formas no imperativas:
6. Ajusta el cuerpo a 72 caracteres
Git nunca ajusta el texto automáticamente. Cuando escribes el cuerpo de un mensaje de commit, debes recordar su margen derecho, y ajustar el texto manualmente.
La recomendación es hacer esto en 72 caracteres, por lo que git tiene mucho espacio para indentar texto mientras se mantiene todo debajo de 80 caracteres en general.
Un buen editor de texto puede ayudar aquí. Es fácil de configurar en Vim, por ejemplo, para ajustar el texto a 72 caracteres cuando se está escribiendo un git commit. Tradicionalmente, sin embargo, los IDEs han sido desastrosos para proveer un apoyo inteligente en el ajuste de texto en los mensajes de commit (aunque en las versiones recientes, IntelliJ IDEA ha conseguido finalmente mejorar sobre esto).
7. Utilizar el cuerpo para explicar qué y porqué en lugar de como
Este commit del repositorio Bitcoin Core es un gran ejemplo de sobre explicar lo que ha cambiado y por qué:
Echa una mirada al diff completo y sólo piensa en la cantidad de tiempo que el autor le ahorro a los colegas y futuros desarrolladores por tomarse el tiempo para proporcionar este contexto, aquí y ahora. Si él no lo hubiera hecho, esto probablemente se perdería para siempre.
En la mayoría de los casos, puedes ignorar los detalles sobre cómo se ha hecho un cambio. El código es generalmente auto-explicativo en este sentido (y si el código es tan complejo como para necesitar ser explicados en prosa, esa es la función de los comentarios en el código fuente). Sólo céntrate en aclarar las razones por las que has realizado el cambio, como funcionaban las cosas antes del cambio (y que había de malo con eso), la forma en que funciona ahora, y por qué decidiste resolverlo de la forma en la que lo hiciste.
¡El futuro programador agradecido puedes ser tú mismo!
Consejos
Aprendé a amar la línea de comandos. Deja el IDE atrás.
Debido a la gran cantidad de subcomandos git que hay, es prudente adoptar la línea de comandos. Git es increíblemente poderoso; los IDEs lo son tambien, pero cada uno a su manera. Yo uso un IDE todos los días (IntelliJ IDEA) y he utilizado otros extensivamente (Eclipse), pero nunca he visto una integración del IDE con git que coincida con la facilidad y el poder de la línea de comandos (una vez que lo sepas hacer).
Ciertas funciones de los IDE relacionadas con git son invaluables, como llamar a
git rm
cuando eliminamos un archivo, y hacer las cosas bien congit
al renombrarlo. Todo se cae cuando se comienza a intentar hacer commits, merge, rebase, o hacer un análisis sofisticado de la historia a través del IDE.Cuando se trata de utilizar todo el poder de git, la línea de comandos es la manera.
Recuerda que si usas Bash o Z shell, hay scripts de autocompletado que alivian gran parte del dolor de recordar los subcomandos.
Lee Pro Git
El libro Pro Git está disponible en línea de forma gratuita, y es fantástico. ¡Aprovechalo!
Silenciar una pestaña en Chrome
Algo que empece a necesitar, y no encontré la forma de hacerlo en Firefox, es tener varias pestañas con “audio”, pero querer silenciar algunas en particular y no otras.
Silenciar una aplicación es relativamente fácil en los escritorios de hoy en día, en mi caso con Ubuntu Gnome, el panel de configuración de audio permite silenciar una Aplicación completa. Pero esto es mas especifico.
Dentro de un Browser, poder indicar que se silencie algunas pestañas si y otras no. Esto es muy útil en casos como en los que alguna aplicación Flash que no tenga control de volumen, no hay forma de dejarla corriendo sin que el sonido tape otras pestañas (Donde estemos mirando un video de Youtube, por decir un caso).
Diff y Patch en 10 minutos
Típico post rápido, esta pagina siempre la tengo q volver a buscar en Google para acordarme la sintaxis de Diff y Patch, comandos para crear parches de código (y aplicarlos). http://stephenjungels.com/jungels.net/articles/diff-patch-ten-minutes.html La agrego porque últimamente la tenia en una pestaña abierta de forma constante y ya era molesto, queda acá para el archivo.
Elegir el DNS abierto más rápido
En CommandLineFu siempre se comparten snippets de código interesante. Hoy me encontré con el siguiente:
Ver menú del Grub sin editar /etc/default/grub
Siguiendo con el envión de postear cosas cortas, dejo un tip que siempre me olvido a la hora de usar el Grub.
Ping: Ver estadísticas sin cortar la ejecución
Vía systemadmin.es me encuentro con que hay una manera de ver las estadísticas del ping sin cortar la ejecución del mismo. Mientras se ejecuta un ping, hay que enviar la señal SIGQUIT (Se logra con CTRL+’\’). La salida del ping usando esto luce mas o menos de esta manera: $ ping localhost PING localhost (127.0.0.1) […]
Avances sobre mi trabajo de Tesis
Cuando hay poca actividad por esta vía, es porque tengo mucho que hacer en mi trabajo y estudio, así que eso es bueno en lineas generales. Diciembre fue un mes bastante activo desde lo académico (En mi trabajo también, pero eso es otra historia). Fui invitado a las JCU como Estudiante que esta realizando su […]
Mi experiencia con Chromecast
Introducción Aprovechando que era una de las pocas cosas no infladas en precio del CyberMonday que se hizo en Argentina, me compre un Chromecast de Google. A diferencia de mi post anterior donde me dedique a criticar a Google, en este me encuentro con un buen producto, que me sorprendió hasta el momento y me […]
Desarrollo en Hadoop
Como ya comenté anteriormente, me encuentro realizando mi tesis de grado en un tema que propone una cruza de las áreas de Big Data y Recuperación de Información. En dicho contexto, utilizo Hadoop como Framework y Java como lenguaje de desarrollo. En dicha oportunidad prometí un post con contenido sobre desarrollo para Hadoop. Acá les […]
Inbox by Gmail: Una visión
Lo que sigue será una visión personal acerca de la ultima aplicación de Google: Inbox. El objetivo de esta app intenta ser, según entiendo, ofrecer una capa de servicios que se integren a Gmail, pero que permitan usos no clásicos del mismo. Este es un análisis en caliente: Llevo probando la aplicación en cuestión un […]