Buenas prácticas de uso de un sistema de control de versiones (i)

[MOD 081109(2): Ficheros de configuración del ide]
[MOD 081109(1): Formatea tu código antes de subirlo]

Este post es una recolección de lo que yo considero como buenas prácticas para el uso de un sistema de control de versiones (en adelante SCV). Esta recolección es fruto de mi experiencia usando tanto CVS como Subversion en múltiples proyectos con equipos formados con desde 2 hasta 5 desarrolladores donde he visto de todo (bueno y malo) y además de lo que he podido aprender leyendo a otra gente, en especial el libro Pragmatic Version Control using CVS.

Aún así lo que a mi me parezca como buena práctica podría no serlo para otros o existir una manera mejor de hacer las cosas, así que estaré encantado de leer vuestros comentarios como siempre.

Updates

Antes de nada haz un update. No empieces a programar sin estar seguro de que tu copia local del proyecto está actualizada. Evitarás caer en conflictos con otras modificaciones ya realizadas y programar algo que ya ha hecho un compañero.

Analiza los cambios realizados por tus compañeros. No le des al botón y punto. Al menos en los ficheros relacionados con tu tarea actual.

Usa un cliente y editor potente, como el de Eclipse, para comparar tu copia local de un fichero con la copia remota del servidor.

Commits

No hagas commit de algo roto. Antes de subir algo, asegúrate de que como mínimo compila (perogrullo?), la aplicación se construye bien y el servidor arranca. Un par de pruebas facilonas estaría bien, si son tests automatizados y repetibles mucho mejor. Para nota si compruebas que los tests existentes relacionados no fallan. Matrícula si añades el javadoc y pasas antes un analizador de código, tipo checkstyle, para una revisión automatizada. Intenta ser lo más estricto posible con esto, sobretodo si no cuentas con un sistema de integración continua que detecte de forma automática los fallos que se van introduciendo en el proyecto, al final ese trabajo hay que hacerlo y sale mejor poco a poco y cuando las cosas están frescas que todo al final, la semana antes de la entrega.

Formatea tu código antes de subirlo. Con un ide decente es una simple combinación de teclas o un click de ratón y evitarás conflictos.

Realiza commits regularmente. En plena fase de desarrollo lo normal sería realizar al menos un commit al día. No dejes que se acumulen modificaciones de muchos días sin subir o te llevarás más de una sorpresa en forma de conflicto en todas tus modificaciones.

Comentarios

Comenta siempre tus commits. Por mucha pereza que te de, por inútil que creas que sea, comenta tus commits.

Usa comentarios inteligentes y normalizados. Por ejemplo, clasifica los comentarios haciendo que empiecen por los prefijos ADD para nuevas caracteristicas, MOD para modificaciones y FIX para bugfixes.

Si usas un gestor de issues, tipo Jira, Trac, Mantis, etc., indica en el comentario el identificador de los issues afectados. De este modo conseguirás trazabilidad entre los issues y el código.

Estructura de un proyecto en SCV

La estructura del proyecto en el SCV debe contener todo lo necesario para construir la aplicación una vez realizado el checkout. Esto implica que si el proyecto no usa un sistema que gestione y obtenga las dependencias, como Maven o Ivy, debes añadirlas a la estructura para que estén siempre disponibles.

Sube los ficheros propios de configuración del ide sólo si es el oficial de tu organización. Un proyecto debe poder construirse de forma automática e independiente a cualquier ide por lo que no hace falta incluir los ficheros de configuración del proyecto dentro de ningún ide para cumplir con la buena práctica anterior. Sin embargo, como a los junior suele costarles demasiado configurar un proyecto en un ide, suele ser relativamente útil subir los ficheros de configuración del ide oficial de la empresa aunque contraproducente porque entonces los junior si que nunca aprenden y cambiar la ruta del JDK puede convertirse en un trauma.

No subas ficheros que son generados de forma automática como parte del propio ciclo de construcción del proyecto, como los ficheros .class, javadoc, reports o el mismo war. Como norma diría que se debe ignorar la carpeta build completa. Aquí yo hago siempre una excepción que son los ficheros .java generados a partir de un fichero wsdl, yo suelo añadirlos en la estructura SCV porque no me gusta bajarme un proyecto que no compila de primeras, no suelen cambiar con frecuencia y además su generación puede llegar a ser bastante lenta.

Conflictos

Analízalos con calma. Aunque el primer instinto es llamar al que hizo el último commit, la mayoría de los conflictos suelen ser triviales y con ayuda de un editor potente y un poco de atención podrás resolverlos solo.

Si necesitas ayuda pídela. Aún así puede que necesites ayuda, llevas poco tiempo en el proyecto, aún eres un junior, el fichero ha cambiado totalmente, crees que han podido introducir un bug,... no pasa nada, mejor que llames a tu compañero y lo resolvais juntos antes de meter la pata con tu código y el suyo.

Comenta el código una vez resuelto el conflicto si has modificado su funcionalidad. En la próxima actualización tu compañero verá que has cambiado su código, mejor que lea el motivo en el propio código antes de que te dedique algún bramido.


Esto sería todo para una primera parte, he dejado los temas avanzados y más interesantes como tags, branches y merges para una próxima segunda parte.