"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."
At Payload, we use GitHub Issues differently from other open-source repos. Our approach has some interesting pros and cons.
We've been doing a lot of thinking lately about how to surface our public roadmap, how to best use both GitHub Discussions and Issues, and where to track what the team is working on so that it's all public. The move elsewhere online seems to be to use Issues to track both bugs and future features / roadmap items, but I've always had a few problems with that approach. And we're trying something else. It seems to be working—earlier this week, we hit zero open issues.
Obviously it's unrealistic to keep our issues this low, but I attribute this directly to the fact that we aren't following the standard open-source issue usage by the book. First and foremost, I want to take a second to think about what the word "issue" means. Without looking it up, to me, it means "something wrong." Obviously it's got lots of meanings and can imply lots of things but go ask your grandma what it means to her. She'll probably say something like I said.
Because of this, I've always had a problem with using issues for anything more than exactly that—bugs, things wrong with the software, etc. And I've been pretty adamant, for better or for worse, that we use GitHub Issues solely for those types of things. I guess we engineers are suckers for semantics. Me included.
Our love for semantics means our issues are reserved for bugs. We're not the first to do this, but it's pretty common to go to a big open-source repo and see 1 fafillion open issues. Typically, issue labels are used to differentiate between enhancements, bugs, chores, "good first issues", etc. So if you are coming into a repo and you want to evaluate what you can expect from the product's stability / etc, you'd need to filter by label bug or similar. If we keep issues clean and true to what the word "issue" truly represents, they can paint a very accurate, crowdsourced, at-a-glance picture of what you can expect to run into with our product.
But the noise that comes from mixing bugs with features, etc. creates cognitive dissonance. It makes it difficult to see what is truly considered as a bug (officially classified by the repo maintainers) and what are issues that are maybe real, but not yet officially classified as "bug". It also muddies up the waters for the team that needs to manage those issues, because they have to filter through a sea of noise to prioritize what they should be working on. To get an accurate picture you need to figure out what labels the repo uses to classify "confirmed bugs", what labels might be used for "unconfirmed bugs", and then what issues might simply just not be labeled yet, although potentially represent real issues that you could run into.
For new features, Q&A, help, and everything else, we point our community to our GitHub discussions or Discord #community-help.
GitHub apparently doesn't like this
Unfortunately, our use of Discussions for features / roadmap items does indeed come with some drawbacks. If you're like me, you've noticed that if you Google for help with any given open-source repo, you'll end up in GitHub issues quite frequently. But when's the last time you Googled for help and ended up in GitHub Discussions? My theory is that something is amiss regarding how Google indexes GitHub content. While Issues get great SEO, Discussions barely surface themselves. I actually did a very rudimentary test of this in SF while at a GitHub event with a few GH and Payload employees and we confirmed my SEO suspicions.
This was a few months ago, and we did indeed report our findings up the chain at GH, so maybe it's improved. But I would love GitHub to rectify this issue.
Another thing that's sucky about using Discussions instead of Issues is that you can't use Discussions within GitHub Projects. I would love to use GitHub Projects for our roadmap. I'm a sucker for a Gantt chart. But we can't surface Discussions in Roadmaps at all. Big Bummer.
So we've made do with our Roadmap existing entirely in Discussions, holding out hope for GitHub to improve this at some point in the future. At that point, I'll drink a Bud Heavy nodding to GitHub for a job well done, and for sticking to my semantic guns.
Issues are our top priority
If you've been around for a while, you'll notice that we're fastest at responding to issues. We do our best to respond to Discord threads, GitHub discussions, and issues all the same - but issues get our attention immediately. When an issue opens, the whole team has a tendency to just drop what we're doing and take a look at what's happening.
It's really nice for our engineers if our issues are as moderated as possible. By establishing the pattern that our issues are reserved to "bugs", this greatly reduces the amount of times that our engineers get distracted by help discussions and feature requests. Of course we still do our best to reply to all community help, especially including discussions, but generally discussions are totally OK with a response that comes within a day or so vs. an issue being addressed more quickly.
Even still, keeping issues as our top priority does indeed cause distractions. And that creates friction, breaking our engineering trains-of-thought quite frequently.
As a dev, you could be knee deep in a new feature but then see our #dev-feed Slack channel light up with a new issue report. It's tempting to just shut down work on your new feature and go check out what's going on. I'm 100% guilty of this myself and sometimes feel like I'm on a hamster wheel, just running around day after day trying to close issues as diligently as I can.
But the problem goes deeper. It exacerbates itself if you consider that one engineer might need support from other engineers closer to the feature in order to properly solve it. Might need a rubber duck. Might just want to pair with someone to work through the best solution. Then all of a sudden you'll have two or more engineers distracted—their trains of thought interrupted by the issue butterfly.
Our attempt to keep focus - Bugfix Mondays
To alleviate these ever-so-alluring distractions, we have established a sort of "triage" approach to new issue reports. If it's significant, it gets addressed as soon as possible. But for all other issues, we'll respond and acknowledge—but then we will try and save the fix until Mondays.
On Mondays, every engineer on our team spends the whole day working through issues together. In the morning, we all review each open issue together, assigning issues to those that are best suited to solve the issue. And then we go our separate ways - setting up reproduction environments, and picking through the platform logic to determine what's necessary to fix the issue.
So far, this is has been hugely successful for a variety of reasons. The first is that we get to avoid distractions, which allows our engineering team to focus for the other 4 days of the work week.
But second, and possibly much more important, is that if everyone is in "fix it" mode at the same time, we can bounce back and forth to help each other, brainstorm solutions, and review fixes.
So if engineer A was assigned a bug, but engineer B built the original feature, engineer A can ping B to say "hey, I'd like your eyes on this when you have a sec" and then once B is done, they can jump over to help A.
Knowledge is shared, effectiveness is ensured, and distractions are basically expected. But that's part of what makes our Mondays fun.
Of course this won't work for teams that get over a certain size, but right now, we're scrappy and it's fun. It's also pretty effective.