Over the course of my time on working on a number of different open source projects, I’ve learned several things that contribute to open source project management.
In this series, I’m covering those things within the context of the WordPress Plugin Boilerplate; however, the things mentioned in this series are not specific only to that project, nor are they things that I think are prescriptive for every project.
They are things that I’ve learned and things that I’ve found to be successful. This may change over time.
Nonetheless, a number of these ideas are likely common in team-based environments, but working in open source with team members who are volunteering their time is an entirely different beast.
In this post, I’m going to be talking specifically about issues – not bugs, not defects, not hot fixes – but issues.
Open Source Project Management: Issues
As far as the WordPress Plugin Boilerplate is concerned, the first round of issues I got were often requests for specific features, questions for how to do certain things, or suggestions for improvements.
As far as I’m concerned, all of the above are issues. The thing is, I think that we – as developers – consider “issues” synonymous with bugs or problems, but I don’t think that’s doing the term justice.
Instead, I think that “issue” is a far more general term that represents a wider range of problems that simply bugs.
Because I think that issues are more than just bugs, I’ve tried to come up with a definition that does a better job of representing what an issue actually is.
I’m not claiming it’s perfect, nor am I saying I’d ignore improvements to this :), but what I have for now is:
An issue is anything that impedes the user from reaching their expectations with the project.
This particular definition allows for:
- Bug that exist in the project
- Problems with the code that results in it not acting as the user would expect
- Unclear documentation, code organization, or interface (both UI and class) that prevents a user from users a project
- A question about how or why a particular module is defined
- …and more
The reason that I like to have a broad definition is because it makes it easier to triage how the issue fits into the overall scope of the project.
First, this gives users the ability to open a ticket without feeling the need to define exactly what it is that they are asking about (because they may not actually know – they just know of the problem they’re having).
One of the traps that developers often fall into is expecting the users to be able to clarify if they are submitting a feature request, bug report, general question, and so on.
We’ve got to do a better job of thinking broader. Specifically, in thinking in terms of our users and how they may be perceiving our work.
To that end, when a user opens an issue, I think it’s important to determine how to triage the user’s request:
- Is this a bug?
- Is this a feature request?
- Does this deserve a hot fix?
- Is this a question deserving of some type of support?
- What milestone should this be assigned?
I don’t know if it’s actually a good thing to have a lot of questions or fewer questions when it comes to triaging issues (though I tend to favor having fewer questions), but it’s important to know how to process the incoming issues to know how to sort them, respond to them, and possible assign them to a milestone.
But the ultimate goal of issues is to make sure they are closed, and an issue can’t be close until they are truly resolved.
This means that:
- A question has been answered
- A bug has been resolved
- A hot fix has patched a problem
In short, closing an issue means that whatever was initially opened in the issue tracker has been resolved in whatever way is best representative of the type of issue that was opened.
Of course, it’s okay to ignore issues. There are going to be things that crop up in an issue tracker that aren’t actually issues at all – they are one person’s take on how the project should be or how it ought to be.
And if you’ve got a clear mission and vision for your work, then this may not jive with what you’re planning.
And that’s okay.
I’m not saying to simply dismiss a person as I think every person deserves a respectful reason as to why their recommendation is being rejected, but it’s okay to ignore issues, nonetheless.
Obviously, some things are worth tagging and working on because they contribute to achieving the mission of the project; however, not everything is going to do that and, as such, may be rejected.
Sometimes, however, developers will issue their own pull requests without actually engaging in discussion or opening issues prior to contributing to the project, and although pull requests and the efforts behind them are always appreciated, not everyone is worth merging.
But I’ll cover that in the next article.