¿Que hace a un buen commit?
May 5, 2009 Articulos
Estaba leyendo este artículo de Pablo Santos sobre como los changelogs que puede generar un SCM como Mercurial o Subversion pueden ser utilizados como “documentación” del código y del trabajo que se hizo sobre el y me puse a pensar: ¿Que hace un buen mensaje de commit?
Después de un par de ideas, la mayoría de las cuales las tengo por haberlas leídos en otros blogs, concluí que un buen mensaje cumple con los siguientes puntos.
- Es corto.
- Describe lo que se cambio, si es posible también porque.
- Referencia el ticket/email que hizo necesario el cambio en el código.
- Utilizar prefijos como FIX y ADD para identificar que es lo que se hizo.
Un buen ejemplo es el que puedo encontrar en esta discusión de StackOverflow:
Changed paragraph separation from indentation to vertical space.
…
Fix: Extra image removed.
Fix: CSS patched to give better results when embedded in javadoc.
Add: A javadoc {@link} tag in the lyx, just to show it’s possible.
…
- Moved third party projects to ext folder.
- Added lib folder for binary library files.
…
Fix: Fixed bug #1938.
Add: Implemented change request #39381.
Yo soy de los puristas que creen que el código se debe escribir en ingles, y, por extensión, los commit messages.
Pero hubo un punto de esa misma discusión que me llamo mas la atención:
If you find yourself writing a very long list of changes, consider splitting your commit into smaller parts
Que me llevo a pensar en algo mas importante del mensaje: ¿Que hace a un buen commit?
Un commit es, en la mayoría de los SCM, la acción por la cual los cambios que uno hizo al código en una copia que tenga en su PC son introducidos al repositorio general donde todo el resto puede ver y utilizar el código. El que sea bueno o malo depende de su utilidad, y en el caso de algo tan simple y delineado como “cambios al código” solamente tengo dos opciones: utilizar o descartar esos cambios.
Un buen commit es aquel que me permite ignorarlo o revertirlo,y seguir aprovechando el resto de las funcionalidades de otros commits previos y posteriores. Para que esto sea así un commit debe seguir algunos lineamientos:
- No arreglar o cambiar mas de una caso por commit.
- Los cambios tienen que ser chicos.
Mas de una ves vi joyas en los bugzilla de varios proyectos open source: discusiones, información, incluso documentación. Pero algo que siempre me asombro es que hay grandes patchs (en ambos sentidos, lo que aportan y el tamaño de los mismos), hechos por gente que no colabora habitualmente con el proyecto y que quedan ahí indefinidamente porque al ser tan grandes nadie los aplica como un commit.
Haciendo uso de Trac, una herramienta que incluye un wiki para documentar, un navegador del SCM en uso (Mercurial, SVN y GIT estan soportados, no se otros) y un sistema de tickets, puedo ver los cambios que se van comiteando a los distintos proyectos open source que uso, y es raro ver alguno que supere las 100 líneas con documentación y tests cases incluidos! (Ej: Django)
Dejo para otro post una buena descripción de los distintos SCM.
Mayo 5th, 2009 at 16:14
Pero claro, un comment demasiado largo/explicativo debería estar directamente puesto en la documentación, como por ejemplo la wiki a la que hacés mención, y de última poner una referencia:
“Cambié el modo en el que el Condensador de Flujo hace su función. Mas detalles en la wiki en la entrada #666″.
Los comentarios demasiado triviales como “Nueva versión” (que los he visto ¬¬), rivalizan con los comentarios del código tipo:
// incremento en uno a la variable $var$var++;
// incrementé en uno a la variable $var
Este fui yo, reportándome desde el más allá, y menos aca. O sea: en la cama =\
Mayo 5th, 2009 at 16:23
Muy interesante. Me alentaste a empezar a usar svn para mantener desarrollos (aunque sé que el post iba más allá de ese tema)… siempre fue una materia pendiente, de las tantas. Felicitaciones por el blog! Ya te tengo en el RSS =)
Noviembre 14th, 2009 at 17:17
Buenas querido Ángel,
En esta nueva etapa que emprendí en mi trabajo, veo muy provechoso el uso de las tres herramientas que mencionaste juntas, el uso de Trac asi como de Redmine en la actualidad, la posibilidad de ver vincular las peticiones al resolución de las mismas y poder ver sus modificaciones entre las versiones todo desde la misma herramienta, así como también su documentación.
Ahora queda la pregunta, para que respondas en otro post:
¿Cuál es una buena petición / ticket? , ¿Qué involucra a una buena petición / ticket?
Me gusto mucho el post.
Concreto y simple.