I'm thinking about bringing back a project I first created when I was just starting programming: a local-based issue tracker.
My original thought was that I needed to keep track of tasks for a personal project, and didn't want the annoyance of configuring or using a web-based issue tracker. With many more years of experience under my belt, I've since revised the idea.
I'll probably wind up building this in any case for myself, but before I do, I want to get some feedback from the community as to whether this would be useful to anyone else.
The Idea
Here's the features I have in mind:
The issue tracker's data would be saved in a standardized JSON format. This way, it could be committed to a repository, creating a networked issue tracker without the need for a web interface.
While I'd be building an elegant issue tracker application GUI for working with this JSON file, the standardization would mean that others could be built. Plugins could be created for VSCode, Atom, PyCharm, IntelliJ, Vim, Emacs, or whatever, allowing each developer to use the issue tracker from their IDE of choice.
Another advantage of this system is that, when used with a VCS, it is effectively decentralized. The issue tracker can't "go down", it never needs to be "migrated" between services, and if something happens to the remote, you've got plenty of local copies.
One of the other beautiful implications of a VCS-hosted issue tracker is that it can create an implicit connection between a commit and a closed issue, and that connection runs both ways. For example, if you run a git bisect and find a commit that broke some functionality, you also find the issue that the breaking change was related to; it can now be reopened or amended.
Of course, if hosting the issue data on a VCS doesn't quite work for you, there's nothing stopping you from parking the file on a network share, the cloud, wherever! It's just a JSON file, after all.
I would be building Quantified Task Management fully into this issue tracker, including some of the advanced features that are impossible on existing trackers. (QTM actually got its start in my initial version of this issue tracker, many moons ago.)
The application I'd create for it would be small, fast, and cross-platform. No unnecessary bells and whistles here; just a clean, elegant, "get it down" interface. I'd also be creating a CLI tool, for those who live in the terminal.
I may also be the one to make the VSCode plugin, simply because that's the IDE I'm always using.
Who Is This For?
I can see this issue tracker as potentially useful to...
Personal projects, where setting up an issue tracker online would just be a hassle or overkill; anyone who would create a
TODO.mdcould use this instead.Private projects where one does not desire to pay for or host a full-blown issue tracker, and cannot use most free options because they're not open source.
Academic projects, where the team would otherwise be misusing text messaging and email to track issues.
Hackathon projects, where you need an issue tracker running right now so you can just get coding!
Impromptu work projects, where you would have to cut through a heck of a lot of red tape to get an issue tracker on the company server.
Anyone who spends significant time coding with limited or no internet access, but still wants to see the issue tracker.
Anyone who doesn't want yet one more reason to leave their IDE.
Possible Downsides
I am already aware of some downsides to this idea:
First, because we'd be using a VCS, it would not be real time, and conflicts could occur. Some individuals and teams may not care, as this can be overcome with proper VCS use.
Second, it wouldn't allow non-developers to easily report issues, especially as doing so would require an external tool and the creation of a PR. This could be a negative thing for many open source projects.
However, this may also be a useful thing for teams that regularly have to "clean up" their issue trackers because of users. Phacility (the team behind Phabricator) has this project, and they've begun allowing users to post issues to a public forum, and then manually promoting valid ones to the formal issue tracker themselves.
This could also be overcome if someone creates a web interface (ironic!) with special push permissions.
Done Before?
I was able to find two similar projects: edu-xored/tracker and sanpii/git-issue, but there are three things I'm proposing that they (apparently) don't:
An officially standardized JSON format, published as a specification, so other front-ends can be built.
Quantified Task Management integration, which offers many advantages itself.
An (optional) local GUI frontend. (
trackerhas a web interface, and both have CLI interfaces, but neither have an application frontend.)
Thoughts?
Is this something you can see using? Is there anything I'm overlooking? Share your feedback in the comments, please!
Top comments (8)
Should the data be held in a separate file in the repository?
I'm thinking this might lead to issues where you have to manually merge a machine-generated JSON file, which (besides being no fun) could create problems.
An alternative could be some kind of human-readable (markdown/YAML) issue object embedded in block-comments inside the source-files? If you remove one of these files, for example, any issues pertaining to that file are removed with it.
Like some kind of
TODOannotation on steroids?Waking up this morning, I just thought of building into the issue tracker tool the ability to handle conflict resolutions, so you wouldn't have to do that manually; the interface would prompt you.
I don't dislike the idea of having the block-comments, but given that I (and my team) already comment heavily, that might turn into line noise very quickly.
The other issue, I believe, is that there are many scenarios where I will delete a file so I can start fresh, but I don't want to remove the 20-some-odd issues relating to it, since I'm refactoring.
Third, I typically use
TODOannotation for self-reminders that don't quite warrant an issue, or else to remind myself EXACTLY where I left off during the previous coding session. They rarely stay in place for long.However, perhaps we can use the Git hashes of files to create direct associations between files when necessary.
I do know that conflict resolution, however friendly we make it, will always be a potential issue. That said, I think it would usually show up only if two people are working in the same code territory, which we try to avoid in active teams anyhow. This could almost become an advantage in some cases, because any external modification to a task we were working on would not be able to escape our notice.
What if a commit fixes a bug, but it's not marked as fixed before in a later commit? Then you wouldn't have the implicit connection anymore.
Though I guess sometimes having an implicit connection is better than never having one, people just have to make sure to not commit an issue as solved in a separate commit if they find out after it's pushed.
Maybe an optional field to specify what commit an issue was fixed in? Then the CLI could have an option to look at HEAD similar to how git does.
I love the idea to link issue (and fixes) to a git commit. This is something we don't find in tracker.
I don't use git bisect but maybe another field to specify where the issue started can be useful too.
I definitely agree! That's one of the features I love about Phabricator Maniphest: you can link commits, pull requests (Differentials, on that platform), and issues together in any fashion.
I think part of this is a matter of training developer habits. Since the commit would typically go through a PR, the lack of a closed task could actually be something a reviewer could catch. But, since what's done is done, the developer would still need to manually associate the task with the commit.
Perhaps it would be useful to have some sort of optional notation: you could say
-1for the commit number, to say "back one".I think consistency with git would be essential, so HEAD1 and HEAD~1 and short/partial hash
I like the idea. It's something a colleague and I thought about a lot while working in QA. Essentially, issues are nothing more than versioned documents...
...except, the details. There are hundreds are minor changes made through a typical issue triage, and/or randomly through the day.
There are also log-type entries, where details get appended, rather than modified. Though this is something I wish source control supports as well -- like feature appending logs.
You'd still need a front-end and indexer to support searching and issue listings.
The fundamental idea seems sound, but there's a lot of those damn details. Though I'd not likely support the idea of the code and issues being in the same repository -- the issues have their own lifetime, and may not be code specific.
Well, that there's no saying you must put the issues in the same repository. Because it's just a file, you could track it in another repository, a cloud share, whatever works for your team.
I think you bring up a good point: comments and logs. That makes me think that this is beyond one file. We could use hashes to associate issues with individual files for comments (organized in a dedicated directory), so those won't become merge conflicts.
As I mentioned, I'll build a front-end for this - an application GUI, a CLI interface, and a VSCode plugin. That'll offer the search, browse, and modify tools.