Issue Gardening
"Gardening" in open source projects refers to the background maintenance tasks done to keep the project healthy, growing, and nice looking.
This page is intended to provide guidelines for core developers and some contributors to garden GitHub issues.
It's important to recognize that an issues goes through a lifecycle, in terms of the completeness of the information. Let's call our user Bob.
- Something happens on Bob's computer. (Operation X is slow, there's an error etc.)
- Bob observes the event, and maybe thinks about it.
- Bob verbalizes the event as an issue.
Depending on how Bob has been trained as a QA engineer, he might express the problem in a different way. One way Bob may express this is "sbt needs to update Apache DonkeyKick to 1.2." (Note sbt doesn't use Apache DonkeyKick.) Normally, what we get from Bob is his observation like "Operation X is slow" This is the initial phase of the issue.
The second phase is breaking the issue apart into smaller pieces; and separating into four parts:
- Reproduction steps
- Problems
- Expectations
- Notes (or Analysis)
This is where an issue gardener can come in to help gather more information. The idea is to go back and figure out what Bob did before he observed the problem X, and also ask Bob what he expected to see. Through these parts, we can separate the facts (repro steps) from opinions (problems, expectations), and opinions from speculation.
A good contribution might be commenting:
This issue was originally reported 3 years ago. I tried to reproduce this using 1.1.4, and the error message has improved enough.
some error message.We should close this issue.
See also https://github.com/sbt/sbt/blob/1.x/CONTRIBUTING.md#what-to-report
The third phase is recognizing the severity of the issue. A contributor could help out in highlighting the severity of the issue, by commenting on GitHub issue or get maintainer's attention through Gitter etc. During this phase, prioritization might also take place (Note severity and prioritization are independent, also known as "triage"). Also note that thus far, the issue lives mostly in what I call problem space.
In the fourth phase, we jump into solution space and start adding more analysis to find out the cause, and seek for the bug fix. A useful information is figuring out when the problem started happening, and which pull request or commits introduced the issue. Once they are identified, the source code that was touched in the pull request is likely the first place you would look into for the fix. If you are familiar with the sbt code base, guiding a potential contributor about these information could be helpful. Be sure to use "may" or "might" if it's a guess.
GitHub issue should be used mostly to track bugs and ready-to-go tasks. As such, from time to time older issues (especially feature requests) should be reviewed and closed when it's been inactive.
"Help wanted" is a signal to the community that sbt project is looking for help on the task. As such, we should pick out only the issues that the current maintainers will accept pull requests. For example "Adopt Technology X in replacement of Y" should not have "Help wanted" label unless there's a strong consensus around it. Otherwise, contributors might pick it up, spend some time, only to be rejected in the pull request.
It's recommended that we follow issue template so that the acceptance criteria are clear.
See Good First Issues.