Reinventing issue tracking: Local-first and Git-native

Local-first and Git-native issue tracking presents a novel approach to managing issues within a project. The traditional method involves creating a .issues/ directory in the project root, where each file represents an issue, but this approach has several drawbacks. Issue tracking becomes cumbersome when the project gains momentum, as frequent issue creation, editing, and closing require constant rebasing, leading to a frustrating user experience.

Git stores tracking information in refs, which can be used to store issue data without cluttering the source tree. By assigning each issue an autoincrementing integer and storing it in a ref addressed by that index, issue data can be kept separate from the code while still being part of the repository. However, using Git in this unconventional way results in added complexity, multiple IDs for a single issue, and challenges around conflict resolution and invalid data.

After some reflection, it became clear that the most elegant solution is to work with Git the way it was designed to be used. Instead of forcing Git to behave like a relational database, the solution is to store issue data distinctly from the source code. The Manganin project now uses a separate repository for issue tracking, which is not visible in the list of repositories on the frontends.

This approach allows for a seamless user experience, with issues stored as files in a hidden sister repository. Git's file system and other tools support this method well, making it an efficient and ergonomic way to manage project issues.