Earlier this week, Payload hit zero open issues which is pretty wild to me. When is the last time you saw a repo with 9K stars and zero open issues?
Obviously it's unrealistic to keep our issues at zero, but I attribute our low issue count to a lot of different tactics that we employ at Payload. 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 Payload uses GitHub Issues solely for those types of things. I guess we engineers are suckers for semantics. Me included.
Payload's 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 Payload.
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, Payload's 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 for Payload are 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 Payload 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.
You could be knee deep in a new feature at Payload 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 at Payload 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 Payload 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.
Like what we're doing? Give us a star on GitHub
We're trying to change the CMS status quo by delivering editors with a great experience, but first and foremost, giving developers a CMS that they don't absolutely despise working with. All of our new features are meant to be extensible and work simply and sanely.
Stop by GitHub and give us a star!
Get up and running with one line
Getting started with Payload is easy—and free forever. Just fire up a new terminal window and run the following command:
npx create-payload-app
Top comments (0)