El Issue y el Commit

(Orientado a quienes usan a diario o no tanto al sistema de "Issues" de git, o mercurial, etc.)

"Issues" no significa BUG.  "Issues" hace referencia a un "asunto a resolver". Un asunto puede ser: un bug, una tarea pendiente, una mejora. Cuando se hace un sistema, no es sano hacer un "commit" con 300 modificaciones, se pierde la escencia del uso de GIT.

Descripción del Issue y clarificación del asunto (issue) a ser resuelto:

Es sano analizar primero "cual es la falla, o mejora o tarea a realizar".  Una vez clara y firme la idea es, entonces: (lo que siempre insisto) escribirla en texto simple:  "mejora que resuelve el problema xyz".

Solo al intentar hacer esto (describir el issue) se aclaran ideas internas de uno mismo, se fuerza a discernir entre que es lo objetivo y que es basura. Reto a cualquiera a que lo haga, cuando lo logran han logrado el paso #1 de la ley de UML: "palabras simples que describan un asunto".  Parece simple, pero no lo es. Tras esto, todo lo que sigue es simple...

Una vez descrito el problema en palabras simples, veran que el problema se resuelve solo: se sabe de antemano que hacer, donde tocar y donde no..y, si hay equipos de desarrolladores involucrados se sabe de antemano a quién se le debe dar la responsabilidad de tal "issue", incluso, a veces se quien debe hacer exactamente qué cosa.  Normalmente, una sola persona es la encargada de tal issue. Síntoma: cuando dos personas son responsables de un mismo issue estamos posiblemente ante la presencia de dos issues distintos.

Finalmente, el trabajo sucio: El issue se crea, se detalla y se procede a resolverlo (cambios en código), se aplican los cambios que afectan exclusivamente "al issue" y no a toda la sarta de asuntos que nos econtramos en el camino, estos requerirán de su propio análisis, si es que no afectan o contribuyen al issue.

"Ruido de Commit" (commit-noise)

Ruido de Commit es toda aquella sarta de basura que quedo en el camino de resolución, que solo produce ruido, no resuelve y solo agranda el commit.

Por ejemplo, resolviendo un problema "XYZ" hemos hallado que hay un error ortográfico: es un issue independiente, por qué ? porque al reparar ese error ni afectamos ni resolvemos el issue. Quiza hayan 10 errores (no vas a hacer un issue por cada error) simplemente haces un nuevo issue que refleje que tu estás "reparando errores ortograficos" y en éste commit haces "solo correcciones ortograficas"...no correcciones "de paso".

Qué sucede si hemos resuelto un issue y mas tarde detectamos que quedó mal hecho ?

No vas a hacer otro issue...porque entonces tendrás un mismo issue en dos partes, lo que si habrá obviamente será un nuevo commit, con los cambios que resuelven el BUG. Al hacer el commit entonces lo etiquetas asi:
git commit -a -m "FIX ISSUE #77 (reopened)"
Luego, vas al issue #77, lo reabres y anotas en él al commit nuevo que se ha generado, con su respectiva documentación.

Qué sucede si hemos resuelto un issue, y dejamos tareas pendientes (TODO: xxx)

Es un nuevo issue. Tipo TASK o ENHANCEMENT. Detallarás en ese nuevo issue el asunto que quieres mejorar.

Los comandos "git diff", "git checkout"

Al hacer el "commit" que resuelve a un determinado "issue", se hace así, en este orden militar:

"git diff"  
previamente una revisión. Descartar con "git checkout" a todo aquel archivo que contiene cambios que no tienen nada que ver con el issue, esto es para limpiar el commit de "ruido de commit".
Por ejemplo, si resolviendo un issue determinado modificamos un archivo "libro.php" que no tenia pito que tocar, pero que en el proceso de resolución del issue ha sido modificado por la razón que fuere, pues simplemente lo descartamos:
"git checkout ruta/abc/libro.php"
se han descartado todos los cambios en "libro.php", quedando el commit libre de: "ruido de commit"

"git commit -a -m 'FIX ISSUE #99' "si, el issue 99 previamente creado y descrito.

"git push"
hemos enviado la criatura al repositorio.

Es limpio. ayuda a quienes tengan que lidiar con el codigo que hemos creado y nos ayuda a nosotros mismos a hacer buen software.