Tips for keeping your Open Source Software issues tracker tidy

Charlie Somerville recently tweeted he wished there was a good guide about maintaining open source software:

In between consultancy jobs and building projects for our clients, our team is directly involved in many Open Source Projects. So after exchanging some messages, I realized it would be useful to document some of the common practices we do at Plataformatec for maintaining Open Source Software.

Although this post is not a complete guide, it does share our experience of maintaining and working on the issues tracker of many projects like Rails, Simple Form, Devise, and lately Elixir.

Avoid burnout

One of the most important things when it comes to OSS is to avoid burnout. This is extremely important for small projects, which mostly depend on one or two contributors. If someone burns out in large projects, there is always someone else to take on the issues tracker and maintenance work until you gather your energy back.

For small projects though, if you need to step away, it likely means the project will go unmaintained for a while, which will just make the situation worse as issues will continue to arrive.

So a lot of what we will discuss here is meant to avoid burnout. Here are two examples:

  1. Avoid issues from piling on – it is likely that, if the issues tracker has 30 open issues, you will feel less and less compelled to work on them;

  2. Learn how to say “no” – merging code or features you are not a 100% comfortable with may makes thing worse. Every time there is a bug on that particular feature, you may feel less compelled to work on it or even not be willing to improve/refactor the code in the future, etc;

Of course different developers have different reasons to burnout, so whenever you find yourself lacking the energy to work on a project, try to understand why the energy isn’t there and find ways to avoid the problem from repeating in the future. file

If you are hosting your project on GitHub, GitHub allows you to place a file with instructions on how to contribute to the project. For example, here are the files for Devise and Elixir projects.

Remember the community wants the same as you: the best for your Open Source project. So having detailed instructions on how to collaborate and contribute to the project helps both you and the community. You will have more detailed bug reports, better patches/pull requests, and other developers will find it easier to give back.

However keep in mind that there will still be incomplete or wrong reports from developers that didn’t read the file. That leads us to the next tip.

ABC (Always Be Closing)

If you have ever been to a sales workshop or read about how to improve your sales skills, it is very likely you have seen Alec Baldwin’s speech from Glengarry Glen Ross:

Although we are not doing any sales here, I strongly apply the concept of “Always Be Closing” to the issues tracker. I am always, actively, closing issues. Here are the main reasons I close open issues:

  • The user has not read the and have posted a bug report without the relevant information like OS, software versions, stacktraces, etc;

  • Users are asking questions on the issues tracker when a project has a specific channel for those, like a mailing list or a tag on Stack Overflow;

  • The proposed feature is too complex to not be worth the time that it requires to be implemented. Or you don’t see the possibility for the feature to be implemented in a medium-term plan;

Usually the first thing I do in the morning is to give a quick pass at my inbox looking specifically at open issues. Issues that are invalid or that cannot be acted on are closed with the proper message. In case the user provides the missing information after a bad bug report is closed, the issue will be reopened in the next morning. This activity only takes a couple minutes of your morning, which you can do while you sip your hot coffee. 🙂

Soon after I adopted this workflow, Vasiliy Ermolovich noticed most of the time I was closing issues with similar reasons, and he has created the extremely useful José vs OSS project which integrates with Firefox and Chrome to help me close issues more quickly. This project has probably saved me days of work!

Ask for contributions

The community is there to help you! There are many ways you can reduce your workload by interacting with the community:

  • Depending on the project, asking a sample application to reproduce the issue is extremely helpful. A lot of bug reports are closed after the reporter tries to reproduce the issue and, in the process, they find out the bug was caused by something specific to their application. It saves you precious hours from trying to reproduce a bug that you would never find!

  • If a user reports a bug, ask the user if he/she feels comfortable to send a pull request with a fix. If you have an idea of where the bug is, send the user links to the relevant part of code, and make it clear you are available in case there are any questions;

  • For Elixir, we are experimenting with tagging issues with their “perceived difficulty”, so users who want to contribute to the language can help you solve existing issues. I often list small/medium features we plan to tackle in there and often they are implemented by the community and sent as pull requests;

Find out what works for you and the community

The important thing is to find out what works for you, the other maintainers and the community. For example, while working on Elixir, I was used to close features requests that I could see that would not be part of the language in the next 6 months, even though they were features I liked too! This eventually led to some questions from the community about the approach taken in our issues tracker.

The truth is: if the feature is really useful, you will hear about it many more times! I explained the approach to the community and showed how not having such entries in the issues tracker helps us keep focus on actual bug reports and actionable tasks. Which led everyone to agree with this direction.

Try things and listen to the feedback and hopefully you will find a workflow that works nicely for everyone involved!

Be nice!

Finally, be nice and be polite! Let your contributors know that you appreciate their work as much as they appreciate yours!

What about you? Do you have any tips to share regarding OSS projects maintenance?

4 responses to “Tips for keeping your Open Source Software issues tracker tidy”

  1. Personally, I don’t enjoy such guide rules. I much prefer to encourage discussion over the “always closing” approach. For example, take this ticket on Rails:

    There was simply no discussion around it. “I don’t like it” -> “Yeah, me too” -> “closed”.

    I simply don’t see how this is good for the community…

    This is yet another example where the discussion has ended prematurely by closing the ticket:

    And those are not exceptions from what I’ve seen with regards to tickets handling in Rails at least. Also, the way the Rails core team approaches the issues and bug requests are mostly the reason why I stopped trying to contribute to Rails long ago.

    I sincerely hope other OSS projects don’t follow this guidelines…

  2. josevalim says:

    Rodrigo, that depends on the team, but in my opinion the issues tracker is not the place to have a discussion about features in project of the size of Rails. It has very low visibility (mostly because only the project maintainers receive notifications) so it always end-up being a decision in between the maintainers of the project and the contributor.

    That is exactly the point of the blog post. The issues tracker should focus on *actionable issues*. The point is not to remove all discussions but to *move discussions to the appropriate medium*. It is much healthier for an open source project to have its bugs clearly laid out in the tracker than in a mixture of personal feature requests, questions and incomplete bug reports.

    Note the second issue you linked has not been closed but still there is no discussion. Why aren’t other people being part of the conversation and answering your questions? Maybe in part because there are other 600 open issues? And once you reach this point, it is much harder to improve because the maintainer motivation decreases and the response time gets even worse. Many projects today resort to expiring issues with no comments after 3 months or even resetting the whole issues tracker by declaring bankruptcy! How is that better for the community?

  3. I guess this really comes down to each maintainer preferences. I know that by no means my little OSS projects get much activities like the projects you maintain, so of course I have no idea how I would deal with tickets if I were maintaing some largely used software.

    But currently, I simply don’t stress if my projects have many open issues and I avoid closing any issue until the discussion is over or until I’m already decided on not to accept some feature request cause I don’t think it fits the project goals and then I state that when closing the tickets.

    My take is that GitHub’s issues is usually used even by large projects, like Rails, when it probably shouldn’t as it lacks some interesting features.

    For my private projects we use Redmine and we have a few subprojects as well and I can easily filter the open tickets by priority, type (bug, feature, etc) or basically anything I need.

    I find it very helpful to concentrate discussions on the tickets rather than on mailing lists or StackOverflow. But I realize that this is my personal take on it and that you probably prefer a simpler issue tracker like GitHub’s one and only handle bugs there.

    For my private projects we have tons of feature requests and I don’t feel stressed about that. I work on them by priority order or some other criteria but it simply doesn’t stress me if I can’t get all of them down to zero until the end of the week or the year.

    “The issues tracker should focus on *actionable issues*.”

    The two examples I pointed out (and I could point others as well if you prefer) were actionable in my opinion. And yes, after posting the comment I noticed one of them was still open… I just got confused by other “closed” mentions while reading the ticket.

    With regards to incomplete bug reports, I’d give some time for the reporter to fill out the missing information and after a while without feedback I’d then close the ticket. Just not immediately. When that happens for my private projects, I check such issues with the “Feedback” status so that I don’t look at them again until it changes or when I’m doing some clean-up on old tickets…

    I feel most of the reasons for the guideline you suggest in this article comes from the lacking of the GitHub issues system. Also they seem to be required by large projects, but maybe not at all for smaller ones. Maybe the reasons wouldn’t apply for other projects using more feature-complete issues tracker systems.

  4. apotonick says:

    Cool, thanks for sharing that. I find the “Close Early Policy” interesting, the reasons you guys bring up for that are valid. So far I tried to do the opposite:

    * When a question, I try to reply until sorted (often by other users) and then close it as soon as possible.
    * I always leave feature requests open (when I like them), even when they imply huge refactorings. That is actually annoying as I lose track, and here I kinda like your suggestion.
    * Sometimes people don’t come back. I close them then.

    I guess a problem is Github’s issue tracker itself. I would like to have different “channels” (as you called them) in there, so I could categorize stuff into

    * Questions/Support
    * Feature Request
    * Bug!!!!

    Thanks again guys and keep rockin’!!!