One of the goals of the new GNOME project handbook is to provide effective guidelines for contributors. Most of the guidelines are based on recommendations that GNOME already had, which were then improved and updated. These improvements were based on input from others in the project, as well as by drawing on recommendations from elsewhere.
The best example of this effort was around issue management. Before the handbook, GNOME’s issue management guidelines were seriously out of date, and were incomplete in a number of areas. Now we have shiny new issue management guidelines which are full of good advice and wisdom!
The state of our issue trackers matters. An issue tracker with thousands of open issues is intimidating to a new contributor. Likewise, lots of issues without a clear status or resolution makes it difficult for potential contributors to know what to do. My hope is that, with effective issue management guidelines, GNOME can improve the overall state of its issue trackers.
So what magic sauce does the handbook recommend to turn an out of control and burdensome issue tracker into a source of calm and delight, I hear you ask? The formula is fairly simple:
- Review all incoming issues, and regularly conduct reviews of old issues, in order to weed out reports which are ambiguous, obsolete, duplicates, and so on
- Close issues which haven’t seen activity in over a year
- Apply the “needs design” and “needs info” labels as needed
- Close issues that have been labelled “need info” for 6 weeks
- Issues labelled “needs design” get closed after 1 year of inactivity, like any other
- Recruit contributors to help with issue management
To some readers this is probably controversial advice, and likely conflicts with their existing practice. However, there’s nothing new about these issue management procedures. The current incarnation has been in place since 2009, and some aspects of them are even older. Also, personally speaking, I’m of the view that effective issue management requires taking a strong line (being strong doesn’t mean being impolite, I should add – quite the opposite). From a project perspective, it is more important to keep the issue tracker focused than it is to maintain a database of every single tiny flaw in its software.
The guidelines definitely need some more work. There will undoubtedly be some cases where an issue needs to be kept open despite it being untouched for a year, for example, and we should figure out how to reflect that in the guidelines. I also feel that the existing guidelines could be simplified, to make them easier to read and consume.
I’d be really interested to hear what changes people think are necessary. It is important for the guidelines to be something that maintainers feel that they can realistically implement. The guidelines are not set in stone.
That said, it would also be awesome if more maintainers were to put the current issue management guidelines into practice in their modules. I do think that they represent a good way to get control of an issue tracker, and this could be a really powerful way for us to make GNOME more approachable to new contributors.
I think the guidelines in the handbook are great. They’re not overly detailed and they give clear guidance on how to manage the tracker.
Your point about encouraging contributors to take on issue management is a good one. Issue tracker gardening is one of those areas where a person doesn’t need deep technical expertise to make valuable contributions. I highlighted it in a blog post about how to get started in open source project management.
I agree with the idea of not letting the issue tracker be a dumping ground for feature requests. Or maybe it’s better to say that it shouldn’t be a wish list. When a request is relatively well specified, or if someone is ready to start working on it, that’s a good time to add it to the tracker. This is where having a clearly-articulated description of what the project is (and isn’t) helps, too. I probably have blog-length thoughts to write down about this at some point.
I think this is good stuff. Closing issues can be difficult – I would definitely would prefer if people asked folks like myself when in doubt on how to close it with minimum of drama. GNOME attracts needless turbulence which can create mental health issues.
I’m more than happy to close issues and deal with the fall out . Closing issues requires a certain level of sensitivity I’ve found. (as someone who was both in IT and works as a developer engagement person)
As a user, it can be frustrating to see an issue be closed after a specified time just because there hasn’t been any activity. Especially when more people agree the RFE is a good thing to have, or when the issue is still present and bothering you.
The way how and when issues are closed plays an important role.
Manually or automated, with or without an announcement before closing, what constitutes ‘activity’ to keep it open, and should closing be revokable or not and by who?
Automatic closing removes a maintenance burden. When an issue is marked ‘needs-info’ and no info has been provided, there’s not much a dev can do anymore. Especially these could be closed automatically. For other issues, closing might require some consideration.
When closing is done automatically, a heads-up announcement, I think, would be appreciated in all cases. It allows for motivating someone to take action. Even just to know if a problem still exists and bothers people.
In plenty of cases it might be obvious that an issue is still present. In these cases just a ‘still present’ message after an announcement might seem redundant, but at least it allows knowing if people still care. Up to the maintainer to decide if it validates keeping the issue open, automatically or manually.
If announcements are deemed necessary, these can be automated without issue. I don’t see a reason to burden a maintainer with giving a heads-up manually.
When an issue is closed, especially automatically without consideration, being able to reopen it reduces the effort, with or without frustration, to recreate a ticket by a user if the issue still applies. It being done by the same initial reporter or a new user wanting to report the same after closing.
You don’t have to search in as many closed issues this way, to know if a particular issue has already been taken into consideration.
At the same time, users already have a ‘hard enough time’ to search (sarcasm intended) in open issues before reporting, so this argument might not hold that much weight.
Who would be able to reopen a ticket?
If a closed ticket still allows commenting, it would also require a maintainer to keep following closed tickets. Quite a task if you ask me. To avoid this, one could consider allowing users to reopen closed tickets themselves. An additional ‘locked’ state might be appreciated in this case to avoid users keep opening the same issue.
Ben raises an important point about what should actually be accepted as an issue.
RFEs are more likely to be kept open longer without activity because there hasn’t been somebody who was able to make time for it yet.
Because of this I think RFEs should either be registered elsewhere or treated differently as issues. Simply a longer closing delay as an issue? How and where to manage them elsewhere?
Automatic closing of issues isn’t being proposed, and the guidelines include information on how closing should be done: https://handbook.gnome.org/issues/management.html#be-polite-empathetic