@sindresorhus posted this tweet today about a thing I remember writing about beforehand too (or at least have thought about it a lot): staleness
Controversial opinion: Stale issues in open source projects are fine. Auto-closing issues based on staleness is an annoyance to users and can drive potential contributors away. There must be a better way of handling issue overload.
@sindresorhus (https://twitter.com/sindresorhus/status/1082145283285250048)
Here's a couple of short thoughts I have on the issue of staleness after maintaining things like brackets and our own projects for years.
Gosh, I am glad that my issue was marked as stale and closed
- no-one ever
I, too, consider solutions like stale-bot annoying at best and very harmful at worst. It actively encourages some of the worst practices around: it undermines the user by assuming things without context and increases the signal-to-noise ratio by bumping old issues. Even worse, it forces the original poster and those that have the same issue to repeat those patterns.
It's a poor bandage for the real issue which is not staleness, but the overwhelming amount of work that open source maintenance can be.
Here's a list of ideas that I have found helpful when dealing with issues:
Lead issue creators into the pit of success from the start by creating things like issues templates and contributing guidelines but keep them as simple and flexible as possible. Requiring every field for every issue is most likely not needed anyway and will only confuse the filers from getting to the actual point of the issue. Even worse, quite often we see people leaving the issue templates there unfilled altogether.
If you require repros, make sure that you have templates that are up-to-date, comprehensive and easy-to-use, possibly in online services such as CodeSandbox.
If more information is needed, politely ask for them and mark the issue as such instead of closing the issue outright.
When to close issues then? I'd say close the issues when the problem is solved either by the user themselves with yourself or by a new release/commit/comment or any other actionable point.
The number next to the issues is often perceived as a metric for quality of the codebase when in reality it's more of a combination of popularity, complexity, code, and accessibility. Complex systems inherently have more issues than simple ones and popular things have a vast variety of users ranging from experts to beginners. Writing documentation in one language is HARD but for many users language in itself.
Instead of focusing on the amount, try to focus on the insights the issues give. See uprise of issues regarding upgrading the app? Build more documentation around the upgrade process, outline common issues or maybe even change the code. And like said, old does not invalid and staleness does not mean that the issue is solved.
Not every issue will be solved. Not every issue can be solved. That's super fine.
Many often think that the lack of tooling is the missing link between managing the overwhelming amount of issues and think that moving to other systems like JIRA or Phabricator is the solution to end it all. From my experiences the amount of issues is often reduced, but most likely for the wrong reasons. Rising the barrier of filing the issues is an effective form of gatekeeping, sure, but also reduces the chances of turning issue folks into contributors and even discovering urgent issues!
Instead, see what you can do with the capabilities the platforms provide you out of the box. Something simple like GitHub labels and assignments can be a good start. Assign actionable issues to people. Tag issues with the relevant versions and outline the releases/commits where things have been fixed. Tags like "Triaged" or "Needs info" might not seem super relevant at first, but try coming back to a list of issues after a month. Tag things where you need help as "help wanted" and newcomer issues as "good first PR". Even an ad-hoc priority system of "Urgent", "Must have", "Low priority" can be helpful.
And of course, if you cannot commit time to certain issues, outline it to the person filing the issue and provide links to actionable documents like "how to start developing".
Want to know where the action is? Sort the issues by recently updated or most commented.
Experiment with the features and see how far they take you, no matter how simple they seem at glance.
Note that for some organizations moving the issue tracking to some other system might be the correct solution, YMMV
This one is a thing that I always thought was easy: "find people and they will do the work for you". Turns out that I was totally wrong. Finding the right people is hard work and not everyone wants to be a maintainer, because maintaining is hard work and can be, gasp, overwhelming. There are lots of really popular open source systems without an active maintainer and that's just how the things are.
That said, if you manage to find the correct people or the correct people manage to find you, don't be afraid of empowering them to do real changes. After all, open source (and closed source) thrives from collaboration.
Despite not loving the stale-bot and its friends, automation can be your friend too! Require a CLA? Add a CLA bot! Have a strict policy about code styles? Automate that part of your code reviews! In an optimal case, automation is your and the contributor's friend but as always: context is the key and not everything can be left up for bots (for now...)
Pretty good, thanks for sharing your thoughts !