GitHub Issues-only project management
blog.placemark.io
blog.placemark.io
After I bought my radio, I found a few firmware issues and looked for a way to communicate them to the manufacturer. No luck on that. There was an active Facebook group, but it was a weird place run by a radio dealer who would ban you for discussing anything he thought might interfere with his business.
So I made a repo and started adding issues for the things I'd noticed. People found it and it took on a life of its own. The most popular issue is a lengthy collaboration among several hams who worked out a way to load the D878UV firmware onto later versions of the D868UV (the hardware is the same).
This was one of the topics that would get you banned on that Facebook group, as the group owner would rather sell you a new radio. The funny part is that the upgrade involves buying a special programming board and considerable time and effort, plus the risk of ruining your radio. So it was really just a labor of love for a few hams who had a blast working out how to do the upgrade.
Hams may not build our own radios as much as we used to, but we can still hack the firmware!
At my last large employer I ended up putting together a custom search engine that searched across a bunch of different places where important stuff ended up - Google Docs and GitHub Wikis and Markdown-in-GitHub and Confluence and Salesforce Support and a mailing list archive and a few others.
Having a single place to search really helped: I had thought that we had bad documentation, but it turned out we actually had pretty good documentation just distributed across too many different places.
1. Would I have control over the "From" name and address for emails that HubDesk sends to users?
2. Do email replies from users get added as comments on the issue?
3. When an issue is created, does HubDesk send a confirmation to the user so they can do follow-up replies even before the rep has done an outward-facing reply?
For #2, yes. You can go back a forth with the user just using commments.
For #3, that's also on my list to add.
Thanks for the feedback!
Github just lacks the few necessary to do project management well, I think. I would love a "backlog view" for Github Projects.
I would love a way to have a separate backlog “column” that doesn’t show in the Project kanban view. I’m keen to try out the new Issues/Project features when they roll out.
Love that the default is private and you have to add @reply to actually reply. I'll give it a try. Do you plan to make money from it? It's not super reassuring to start relying on it if it can get killed tomorrow. Also is there a way to restrict permission to a specific repo for the GitHub integration? "Act on your behalf" is a little scary as a permission.
You can restrict the permissions to just one repository when you authorize the app. There should be a radio button for "All apps" or "Selected Apps". If you select the second one, you can pick the repos where to install it.
I resonate with this blog entry because I agree that the visualizations that more sophisticated tools provide are low-value distractions that ultimately cause more problems than they solve. The most important thing for collaborative development, in my opinion, is a clear, accurate, singular definition of work to be done. From there, you can prioritize and adapt as needed, but spending inordinate amounts of time with visualizations (often to satisfy some non-technical stakeholders) is wasteful allocation of resource time.
My own thinking on task trackers: https://tiamat.tsotech.com/task-tracking
For example, a golden rule of mine is that you should only have one authoritative system used for task-tracking. Any additional system or tool will inevitably lead to confusion about priorities and lost efficiency, despite the appearances to the contrary that lead you to add a tool in the first place.
Once I started using Microsoft To Do, the way that I ran my life/business scheduling became 10-fold more efficient. Any recurring tasks or issues, be it daily, weekly, annually, can be easily scheduled, tracked, and shown as a badge in your taskbar. It's an incredibly integrated, underdiscovered and maybe undervalued app that Microsoft sort of stealth released.
It is so powerful that I deprecated all my no-code JIRA projects and opt to using it instead of a Calendar in my personal life. Would do the same Calendar delete in my business if only it integrated with Teams/Outlook calendar and meeting bookings.
I believe a lot of vocal fans of Wunderlist were upset with how it all went down and didn’t want Microsoft To Do. So there’s lots of internet vocal negativity toward the app possibly.
Generically, we're talking "Kanban board" with swimlanes for the status, tags for categorization, and comments/attachments for discussion tracking.
I'm currently in a position to get some people sync'ed on projects for a client, and I am going to recommend we use Trello.
Kanban is just the right level of organization and visibility without going full agile-daily-standup-sprint overload.
JIRA is a pile of bolted-on features, and no one has ever measured what is essential to project management, so this point strikes me as sort of an ad populum than an argument that JIRA or whatever is more fit for some PM task than Github Issues.
This is what kills me about software project management, at least in Enterprise where I work: its about people consistently communicating to one another; that's it, lest there's something else we can extract as somehow more primordial. Somehow people consistently communicating over a topic has been reified to the point that we mistake the reified things for the thing-in-itself.
I drop a single README.md in the root of the repo that links to the issues and leave it at that.
My gig is still in Trello-land and I'd like to move away from it but companies have a tendency to include biz folks in Trello whereas Github is scary tech world to a lot of them.
I understand they want to get it "right" before opening up to the majority, but project management isn't something a business can sit and wait. People have to use some other tool in the mean time, and once having invested time and effort they won't switch back easily.
Use it to track white papers, project planning documents, a project-wide wiki, et c., if you want to feel like it's for more than just issues. Though having an issues-only project doesn't seem worse to me than using any other stand-alone issue tracker, separate from GH.
GitHub Issues has exactly the set of features that I need. I'm confident I understand 100% of the functionality that it offers, and I use all of that functionality.
(The "GitHub Projects" stuff hasn't stuck for me, but that's presented as an optional layer on top of issues so it's easy to ignore it.)
I also love how programmable Issues are. The APIs (both REST and GraphQL) are easy to use, and the options for automation using GitHub Actions are exciting, though I've not done much with them yet.
I also like having an exit plan for this kind of tool, and the API means I can easily get all of my issues data out again. I wrote a tool called github-to-sqlite which exports my data to SQLite and I use it to build a SQLite database that brings together data from many of my projects so I can search and query it in one place - demo here: https://github-to-sqlite.dogsheep.net/
I think we still want to build another layer on top that is more about how our business works, but GH issues would continue be the one-stop-shop for anything regarding the codebase itself.
"GitHub does not provide issues-only access permissions"
- disable the "packages and registry" menu item for the project (despite disabling it in the permissions) - odd help texts, such as "enable LFS to upload a design" displayed to non-admins - can't hide the service desk menu item, despite permissions.
I understand it's not an easy compromise to balance discovery and user-friendlyness, but then we have people in our community who repeat "gitlab is only for devs" because of this.
Example: https://lab.civicrm.org/support
You can get around this by gzipping everything, because they allow .gz, however I still don't see why I'm not allowed to upload .diff or .patch files.
Having worked in a shop that used GitLab issues for project management, I've come to realize GitHub-style issue trackers work if all your project management boils down to creating and tracking bite-sized blobs of work. It stops being sufficient when you need to actually plan ahead. FWIW, so does Trello. Couple reasons why:
- Issues are flat. Work breaks down into a tree. And no, "epic / ticket / checkboxes in task" is not enough, that's barely two and a half levels. Compare with https://en.wikipedia.org/wiki/Work_breakdown_structure [0].
- Issues are independent. Properly broken down, work in a project has dependencies. That turns a tree of tasks into a directed acyclic graph of tasks - work items depend on other items, often items from different areas in the WBS.
- Issues don't schedule well. Most issue trackers I've seen don't support simultaneously entering planned start/end dates, actual start/end dates, and actual work being done. This means they can't be effectively used to estimate the length of the project, and update that estimate as the project progresses. Forget about any auto-scheduling.
There's a reason why old-school PMs love their Gantt charts so much - they properly reflect the graph-like nature of work, and they let you see the information crucial for planning at a glance.
In my opinion, any system that doesn't support entering DAGs of tasks with planned manual and automatic dates (e.g. "this task will take ~5 days, and starts when that other task ends"), and doesn't allow you to compute the critical path, is not a project management tool, but a glorified TODO list. A good PM tool does what I've outlined above, plus it lets you easily run what-if analysis - that is, play around with estimates, resource availability, task ordering, to explore the space of possible project plans and possible failure modes.
So, in my opinion, neither GitHub/GitLab issues, nor Trello or other Kanban boards, are useful for PM work. I've heard that properly configured Jira just might be. MS Project is a good one, if you ignore its clunky UI and propensity to randomly lock up for no reason.
--
[0] - Even where the Wiki says "For most projects a hierarchy of two to four levels will suffice.", this is in context of "lowest level of detail of the WBS should be longer than a single reporting period", which would be typically a month or more. Tickets in the issue tracker are thus a level below that. So, to properly break a project down, you need ~2-4 levels of structure above your tickets.
A trick I use a lot is to open a "tracking issue" and then link to it from other dependent issues by mentioning its #ID in those issue's descriptions.
The tracking issue automatically shows the open/close status of those other issues, which means I can see at a glance if all of the dependent issues have been completed.
Here's an example: https://github.com/simonw/datasette/issues/1105
It's not nearly as sophisticated as what you're looking for in terms of date estimates and critical paths, but it does work well for light-weight dependency tracking.
Our PM tried to handle this challenge for a while, by writing scripts against GitLab API. This eventually turned out insufficient, so the PM, myself and another coworker set out to find a project management tool that actually does project management. It's after extensive discussions and search that we figured out none of the well-known work tracking products in software development fit the bill.
Best easily-accessible options we've found were: MS Project (if you're on Windows, which we weren't), Jira (if you hire a person full-time just to manage it) and YouTrack from JetBrains (if you hire a person full-time just to script it). There are other options in the corporate PM space, but we didn't get to explore those as a startup (and eventually we've all left the company).
As an experiment this year, for a more reactive phase of engineering in the startup, I experimented with using GitLab Issues and Board to track all engineering & operations work.
I redid the GitLab Labels to have two sets: Kanban state, and color-coded Urgency. Each issue had exactly one from each set.
I used the "blocks/blocked-by" issue linking to do a crude and poorly-visualized approximation of Gantt task dependencies.
For tracking periodic tasks that had a human in the loop (e.g., run this daily data acquisition tool, spend 5 minutes actually checking the infrastructure dashboard, periodic offline backups), they stuck in the Doing Kanban column, and the Due Date changed to the next day they should be run. This worked well, except for one unexpected performance issue: the Issues page for a daily periodic task that included a daily commit and time spend, and occasion comment... was surprisingly slow to fully load (without measuring, after a few months, it was maybe up to 10 seconds, while all those event entries entries were being loaded). It often slows the daily task, which is something that makes people avoid/resent tools, but I imagine speeding it up might be viable.
I also used the "/spend" in the Comments to track individual time spends. (I did the spends only myself, as an experiment; I don't know whether it would go over well with new hires, especially before we'd established unusual trust that it wouldn't be used for play-to-the-metrics nor against anyone.)
The integration with CM workflow is a win for developers and project managers (whether or not they're the same people). The performance is so-so. (For example, one "urgency::
What might make it really-really win for managing projects that are plannable (rather than situated action on a weekly basis) is a solid Gantt view on the same model, plus maybe adding just a little scheduling to the model.
(If GitLab doesn't do it, this project management view could possibly be third-party integration wrt GitLab, like what Instagantt does as a layer over Asana. I'd almost suggest it to Instagannt, though hopefully a bit faster to use, so that project management isn't slowed by tool performance.)
They mostly use only email.
What is a more accessible alternative?
I’ve been trying google docs. Thoughts?
- email notification are batched unless it's an urgent issue. This is such bollocks, I don't know how they get away with this. Gh issues and jira just work. Workaround: use their Webhook and do it yourself. Makes me so angry.
- can't search comments WTF
- I'm a "tabber", but linears super-fancy-SPA bootstrapping is way behind loading a single issue page especially compared to github but also jira
- github has no wysiwyg and linear ONLY has it, but it has so many subtle bugs, especially with lists. But I'm spoiled with notion. Has its own set of problems, but pure editing is great
Oh boi I could go on.
But I agree, for cross teams with non-devs it works great.
https://meta.discourse.org/t/running-a-project-or-team-using...
How do you handle this sort of thing with just Git(hub|lab) issues?
No more dependency on online saas tooling and you can use the search option of your ide / os / command-line to search through them.
I still have to come across a project management software that is delightful and effective at the same time. There are many tools out there, that do one job very good, but in my opinion, none that combine planning, execution and evaluation in a modern and predictive fashion.
> A lightweight comments widget built on GitHub issues. Use GitHub issues for blog comments, wiki pages and more!
> I think it’s worthwhile to lay out an alternative, which is my default: just use GitHub issues for everything.
Insofar as this article is an argument against using Trello etc instead of bug trackers, it's a great article. But insofar as it is really, actually suggesting you use GitHub issues, its value is thin. My rationale is closely related to my stance on Lawrence Kesteloot's essay Java for Everything:
<https://www.teamten.com/lawrence/writings/java-for-everythin...>
This is one of my favorite blog posts of all time—and yet, I don't actually use Java, and I don't exactly think that you should, either. Funnily enough, it has a lot to do with why you shouldn't literally use GitHub issues.
The worst part about Java is actually dealing with the kinds of things that Java programmers do and the general experience of dealing with the Java ecosystem.
Likewise, the worst part about using issues on GitHub is the GitHub community. (The first example cited is a good example of this: "The company internal blog was an issue-only repository. Blog posts were issues, you’d comment on them with comments on issues." This is awful.)
Bug isolation, bug triage, and (most importantly) discipline in your approach to coming up with a fix for a given bug are all excellent skills that can be applied to many things to great effect, but you wouldn't know it looking at the way people use GitHub. It's still far from a norm for people to even provide steps to reproduce a given bug, not to mention the wanton abuse of comments. The example given ironically demonstrates why GitHub issues is _not_ the place that you should be taking cues from.
I especially find the claim that "GitHub issues make it harder for you to procrastinate and pretend" to be pretty comical. GitHub overall seems to favor people doing things that make them look busy (including actually being busy, if only, though, because of how inefficient GitHub's traditional workflows are) at the expense of actually doing things well.
I think some big names are using this approach to right. Like aspnetcore and some other microsoft products
I also dont think that its necessary to point out but I would not advise handing over all business organizing to github as a platform.
GitHub is not the only issue tracker. Git itself is the easiest to migrate off of GitHub, issues is probably close next.
Thanks for the details.
Anecdotally; the author of the blog post and work environments I’ve been in did just that and … reality still exists.
Me thinks personal opinions on how to store data are … personal opinions.
Because if you're worried about that, there's probably a whole bunch of even worse things that they could be doing with access to your source code, secrets and CI infrastructure.
I also use high med low customer impact and low med high difficulty labels as advocated by yc to organize priority.
> or the macOS “Sticky Notes” app that somehow still exists in 2021
Why isn’t Sticky Notes just a view into a particular folder in Notes.app, anyway?
First off, I am not sure why people like Kanban boards so much. It seems like the most inefficient way to display issues possible -- you can't see the details, the title gets cut off into lines of 4 letters each, and you still have horizontal and vertical scroll bars. The idea of Kanban was that if you didn't have space for a card, you wouldn't take on the task. To some extent, this can work for software; you can say "there are a maximum of 3 changes per release", and so if there are 3 cards in the "to be released" column you know you have to do one before anything else can proceed. But nobody has that rule. Meanwhile, does it apply to all the columns? Like, you can't report a bug in the software if the backlog column is full? It makes no sense to me, and I think it's a huge anti-pattern.
I much prefer Linear's cycle view ("sprint view" for those of you that think sportsball metaphors play well with software engineers), where you can group issues and they show up as the category and then a list of issues that take up the entire horizontal width of the window -- so you can see what's in progress, what's to do, what's done, what's released, at a glance. Or during cycle planning, you can group by assignee and see that someone who is on vacation for one week and oncall for the other has 8 XL tasks assigned to them, and not commit to that impossible plan.
I'm not a fan of Github Issues. I find everything I want to do to be very high overhead. If I want to open three issues, I have to navigate to the issues page, click "create new issue", type a title, type a description, click "tags", type the name of the first tag, click it, delete the stuff I already typed, type the name of the next tag, click it, etc. Then you submit, and you see the issue that you just submitted. To file the next issue, you hit back twice, click "new issue", and repeat. It is incredibly tedious, and people flat-out don't file issues for stuff they're working on. (Projects and Milestones are similarly high overhead. They're infinitely configurable, so useless out of the box, and therefore require a bunch of setup you have to do for every project. If you treat Projects as their version of Epics, then you probably need a Terraform script of something just to get the right columns on the board, which as I mentioned I don't even like.) Github's workaround for all of this is some automation to make PRs close issues, and that's about it.
Github is also awful with notifications. If someone comments on an issue assigned to me, nothing happens. If someone @mentions me in a Github issue, it notifies my phone. If someone requests a code review from me, it notifies me on Slack. I don't know how anyone can tolerate a system that is this bad. It's like Microsoft made the product before they even bought it.
My experience with all of this is that people don't file issues for things they're working on, don't close issues that span multiple PRs, don't reply to issues that require their attention (or even know what's assigned to them), and leave tasks 90% done because crucial followup gets forgotten after Github automatically closes an issue. This makes the system actively harmful -- at best, it's a dumping ground for ideas that will never be. If someone was going to do something, they'd just do it. If it goes into Github issues, it is only worth it for "I thought of an idea that will take a month to implement, here it is". Very bad.
This doesn't even scratch the surface of what an issue tracking system can or should do, but is hopefully enough to convince you that it's totally useless. I don't know what issue tracking zen is, except that when I worked at Google their internal tool didn't have any of these problems.
Linear (https://linear.app/) looks really nice. It's like someone took my exact ideas for how an organization should manage projects and made it into a computer program. It's speedy. It tracks exactly the right pieces of information. It lets you take a look at the company's progress towards its goals, across teams, with one click. You can operate it entirely with the keyboard. It has an inbox for everything that requires your specific attention. It understands the concept of issue triage. Really great tool. Miles ahead of Github issues (and the things that integrate with Github issues, like Zenhub).
Avery has some thoughts on the system near the end of his Epic Treatise: https://apenwarr.ca/log/20171213#slide38
...In their ideal form, GitHub issues are homogenous. An issue is a task that you need to complete. If it isn’t a task, it isn’t an issue. If it’s done, it’s closed. If it’s not done, it’s open.
But I guess if trello was enough, it means you don't really have bigger needs than having a list of tasks.
Stop assuming the thousands of companies which use Jira are stupid
FWIW, in my experience I haven’t seen JIRA add anything besides overhead, regardless of how tidy a PM makes it.
Worked great, would recommend.
Having everything as GitHub issues has several benefits: Everyone knows how to use them, great markdown support including images, ability to react and thumb up issues and comments, deep integration in the actual code - well it's github, and it feels rock solid!
Wish you the best!