Reinventing issue tracking: Local-first and Git-native
27 points by matklad
27 points by matklad
No mention of prior work in that space like https://github.com/git-bug/git-bug or https://github.com/dspinellis/git-issue :-(
Thanks for the links! Git-bug looks pretty nice with its UIs, too bad it can't push/pull unless your SSH setup matches the developer's. Which apparently is a known defect for years now. I think this is not the first time that go-git has been a detriment to a piece of software, though I don't remember what project was made unusable to me the last time
Given the requirements, why not issues in a special branch rather than a separate repo? It must have been considered and discarded but at a glance I don’t see why.
I've been noodling on this for a while. There are a few tradeoffs. A branch could give everyone who clones the entire issue tracking history without extra steps; I'm not sure if that's a pro or a con. I'm worried about clone times, but text compresses well. A separate repo allows more flexibility: someone can clone it in a directory where they keep issues for all of their projects, or add it as a git submodule, or whatever they choose. I have a local branch where I'm experimenting with issues-on-branch rather than issues-on-repo, but I'd been sitting on this devlog for officially Too Long(tm) and wanted to get it out there even if the feature isn't in its final form.
or add it as a git submodule
One fun hack here (from git-subtrac) is that you can include a branch of the same repository as a submodule, submodule can come from the same repo.
someone can clone it in a directory where they keep issues for all of their projects
That is also possible with a branch, thanks to git-worktree.
Branches are meant to store code with a shared history that branched off at some point, not meant to store multiple related projects in the same repository, so this approach is somewhat unintuitive to me. Despite that, it probably would work, although you'd need to have a separate copy of the repo (maybe using a worktree) to be able to view issues while working. Honestly, I don't hate the branch approach though.
Branches are meant to store code with a shared history that branched off at some point
Git lets you create orphan branches which "will have no parents and it will be the root of a new history totally disconnected from all the other branches and commits". They have been used for storing things the like the project site (e.j. GitHub Pages run off gh-pages by default. They recommend you to use an orphan branch for that). I wouldn't conflate the common use of an affordance with their purpose.
man git branch does not really advise against them.
I found them quite handy at my last gig; I had a $myself repo in our GitHub organization with orphan branches for experiments. I found this helped avoiding polluting our repository namespace and repository list.
I also had a project where I did a complete restart from scratch and kept the history of the previous iteration as an orphan branch.
I've spent a non-trivial time philosophizing about issues/discussions as close to code&version control as possible. It started with Unison where code is stored in a db, so maybe issues can also be closely co-located to code? What about comments that now can refer to precise AST/versioned code pieces. Transclusion(for a nice UX) etc all kinda fall in to place as well)? We can have very little context switching this way!
In the end I think all of this is possible and good goals to experiment with; I don't think it'll be easy if it's Git-native, though I don't think it'll matter for end users(maybe my first ever technical hot take!?). Issues being close to the code doesn't mean it needs to live as files in the some folder, it means the jump from code to relevant context needs to be as simple and quick as possible. This can be a file in a repo or it can be some data structure stored in a db (CRDT?) or it can be a really, really good CLI or Emacs plugin.
Screenshots/screencasts/multimedia attachments alone seem like that'll be a struggle.
Git-based issue trackers have the problem of not being able to accept issue reports from users or people without commit access generally. As far as I can tell this issue tracker has the same problem. Issues are stored in a separate repo but you still need commit access to file issues.
Presumably the forge can separate commit access to the code from commit access to the issues. As long as the structure of how issues are tracked can be introspected, the forge can determine what kind of operation is being done and apply authz to it.
Manganin (and pretty much all other forges I've looked at) uses githooks for access control, which are quite flexible! Users without commit access to the repo have the ability to make issues by default. I intend it to be configurable per-instance in terms of who can make issues, who can force an issue to be uploaded with invalid syntax, etc. I'm also looking into a pipeline for issue submission for non-users of the forge (people not in the vouch tree).
Filename is the title, file content is the body. How does discussion happen ? Everyone edit the same file? Editing the body over appending to it? How to be notified there is a response to an issue?
What about the state of the issue? Forges often have open/close distinction that make it easy to forget about closed ones, although they are still accessible. With the current design it's not clear if there are subdirectories or not. A directory with thousands of issue filenames gets unwieldy.
See Haxy
Author also has a series of devlog videos on YouTube.
Neat! Haven't watched any videos yet, and the README is pretty sparse. Can you say something about its maturity?
I don't think issues belong in the git tree, the system wasn't designed for that purpose. I don't really see the value in versioning issues either, merge conflicts are the side-effect of a deeper issue. I think a perfectly reasonable alternative is an sqlite db that holds all the issues: easy to store, easy to transfer, easy to update.
you would be surprised by what constitutes a valid path
This is highly dependent on what OS you’re using.
Git probably takes care of normalizing some of this, but I have heard of problems where a repo can’t be checked out on some OSs because of illegal or colliding filenames.
Another big problem is renaming an issue, which happens often. Git can handle renames, but the rename breaks the issue's path. It’s a best practice in anything database-like not to reuse a visible field of a record as a primary key, because inevitably you find a need to change that field.
Apple platforms require normalized UTF-8.
Furthermore: / is allowed, but : is not. HFS+ and APFS use : as the "internal" path separator, and translate it back/forth with / for compatibility... which means that a path created via something like Finder as foo/bar can show up as foo:bar via ls.
hm. I'm not convinced there's a real problem here and the solution (second repo?) was a bit anti-climactic.
That said, issue tracking is a different tool IMO and needs will quickly outgrow this system. For a team this is too restrictive and goes against the unix philosophy of doing one thing well. It's two things now.
That said... Fossil VCS and Radicle using the rad cli interface support issue management.
ps. I must admit that this https://github.com/git-bug/git-bug looks pretty neat for my personal, solo projects since I'm used to working in the CLI. Make me wonder if I should dumb forjego entirely and rely on ssh+bare-git remotes and this tool ...
For a very minimalist approach, see https://github.com/tsoding/tatr. It is not tied to git but since it's plain text files, it works with git.
I have never used tatr, I am happy with forgejo's issue tracker for my projects, but it popped up on youtube yesterday for me, so when I saw this lobsters post I took it as a sign that the universe wanted me to share it here.