Manganin: por qué el seguimiento de issues acabó fuera del árbol de código

El autor de Manganin ha publicado un devlog en el que repasa sus dos intentos fallidos de meter el seguimiento de incidencias dentro del árbol de código y explica por qué acabó guardando los datos de los issues en un repositorio Git separado, con herramientas que hacen de puente entre ambos. Sus requisitos eran claros: todo en Git, manejable desde la terminal, funcional sin conexión y sin obligar a instalar nada extra. La alternativa habitual, levantar un Postgres, añade dependencias, complica el despliegue y crea lock-in. Esa idea de que la funcionalidad básica viva en tu máquina y funcione sin red es lo que llama local-first.

Un directorio de issues y el rebase eterno

El primer diseño era el más obvio: una carpeta .issues/ en la raíz del proyecto, un archivo por incidencia. Tenía su gracia, porque cada rama arrastraba su propio estado y podías cerrar un issue en el mismo commit que lo arreglaba. Al llevar la idea hasta el final apareció el fallo: si un issue se abre en main, ¿a qué ramas activas afecta? ¿Rebasas cada vez para no quedarte atrás? El autor lo descarta sin rodeos: la actividad de los issues es mucho más frecuente que la de los commits de código, y estar haciendo pull constantemente cansa enseguida.

Refs especiales y las tuberías de Git

El segundo intento se apoyó en una técnica que conoció en Recurse Center: apuntar refs con nombres no convencionales a datos arbitrarios, de forma que GitHub los propague fielmente sin entenderlos ni mostrarlos. Cada issue iba a refs/issues/N con un entero autoincremental.

El problema es la ergonomía local. Editar un issue así obliga a encadenar git hash-object -w, git mktree, git commit-tree y git update-ref, con cuatro identificadores distintos para lo que en realidad es un archivo de texto. A cambio se gana atomicidad: si un paso falla, no se actualiza ninguna ref y los objetos acaban en el recolector de basura. El propio autor avisa de que su ejemplo simplifica, y que update-ref necesita parámetros extra para protegerse de condiciones de carrera.

La conclusión, tras darle vueltas un par de semanas, fue dejar de forzar Git para que hiciera de base de datos relacional. Los datos de los issues viven ahora en un repositorio aparte y el tooling se encarga de relacionarlos con el código.

Para quien administra repositorios y equipos, lo aprovechable es el patrón más que el proyecto: qué cuesta meter datos que no son código en Git y por qué conviene separarlos en lugar de mezclarlos. La entrada es un devlog de diseño, no el anuncio de una versión, y no incluye cifras de rendimiento ni un enlace desde el que probarlo. Manganin apenas se presenta más allá de esto. Queda por ver cómo resuelve el puente entre los dos repositorios y qué pasa cuando dos personas tocan el mismo issue a la vez.