Managing a open source community and maintaining its infrastructure, like code repositories and issue trackers, takes time an effort. In the free and open source community this work is often called maintenance. This work is difficult and requires strong technical skills as well as excellent interpersonal skills. It can often seem that this work goes unappreciated, but it is critically important for the health of an open source project.
In The Turing Way we call this work gardening, because that is an analogy for how this kind of activity is about tending to the community, keeping it healthy and helping it grow. This page has instructions and guidelines for our gardeners to help them work.
Guiding principles¶
Maintain quality¶
Gardening work plays an important role in maintaining the quality of a project. Continuous integration processes and code review help to ensure the quality of contributions as they are merged. However, there are many other aspects of the community where gardeners can help.
Gardeners should focus on keeping the quality of issues, discussions and pull requests high. Gardeners shouldn’t be afraid to close items or ask for changes. Gardening work makes items higher quality, which improves the chances they will be seen, have engagement and get completed.
Be a mentor¶
Gardeners can mentor community members, teaching them new skills and encouraging best practice. Gardeners should look to share their knowledge and teach others. However, gardeners shouldn’t feel they have to personally fix problems or take on work when they ask for changes.
Use your knowledge¶
Contributing to a project as a new community member can be intimidating. There is a lot of institutional knowledge that is difficult to learn and share. Gardeners should use their experience to help contributors. For example, recommending people who would be interested in a pull request or pointing to style conventions in the Community Handbook.
Be a human¶
In their work, gardeners may have to take actions that might be difficult for others to accept or understand. For example, closing an issue as “will not fix” or requesting large changes to a pull request. Gardeners may also find taking this kind of action difficult themselves.
Gardeners must remember to be kind to others. If gardeners need to say anything that may be difficult, they should take some time to explain. They should remember to be welcoming; a project can only survive with contributors, and everyone starts as a new contributors.
GitHub item usage¶
To help keep items findable, we use GitHub features for different purposes.
Issues¶
An issue is a task, for example a bug to fix or a feature to add. A good issue should,
be of a reasonable size for one person
or, to coordinate large pieces of work, be a list of sub-issues
have a clear “definition of done”
Examples of bad issues could be,
Too much work for one person or a single pull request
No clear work to be done, a question or a discussion
Pull requests¶
Pull requests are proposals to merge one branch into another.
We encourage people to open pull requests early. This helps make their work visible and get early feedback. Pull requests should be marked as drafts while they are work in progress. They should be marked as ready for review when the author feels it is ready to be merged.
Discussions¶
Discussions are used for conversations which are not necessarily tied to a specific task. They are often broader than issues.
Examples of good discussions are,
Questions about the project
Proposals and new ideas
Polling the community
Discussing the options before opening an issue
Gardening stages¶
These stages correlate roughly with how mature an item is. They are not law but they are intended to help us understand what stage an item is at and what we should be aiming to do to help contributors at each stage.
Sowing¶
Sowing ensures new items have the best chance of success. It makes sure items are visible and well defined.
Fertilising¶
Fertilising helps push in-progress items over the line, so that contributions can be finalised. We help keep contributors engaged and support them to overcome challenges.
Pruning¶
Pruning manages the end of life for items which have gone stale. This step keeps the repository clean, closing inactive or completed work while leaving the option for it to be continued in the future.
Checklists¶
Issues¶
Sowing¶
Ensure it is in the correct repository
If not, move to a more appropriate repository
Ensure it is an issue
Move to a discussion if appropriate
Ensure there is a definition of done
Ask the author to find one if this isn’t clear
Move to a discussion if there needs to be a discussion to find one
Close as unfixable if one cannot be found
Assign appropriate labels
Tag (or assign) community members who may be interested or who can help
Fertilising¶
Ensure issue is in action
Check who is working on the issue and assign
Understand progress and challenges
Check what support contributors need to fix the issue
Support assignees
Tag community members who can help
Invite to post a Slack message
Invite to collaboration cafe
Pruning¶
Handle stale issues
If there is no stale label, mark as stale and leave a message
If there is a stale label and 30 days have passed, close the issue as stale
Pull requests¶
Sowing¶
Ensure it has the correct status
Convert to “Draft” if it is still work in progress
Convert to “Ready for review” if it is ready for final reviews
Assign appropriate labels
Assign or tag potential reviewers
Fertilising¶
Check progress with the authors
Ask how close are they to finished
Understand what support they need
Support assignees
Tag community members who can help
Invite to post a Slack message
Invite to collaboration cafe
Arrange for someone to adopt the PR if the author no longer has time
Pruning¶
Merge if it is ready, passes tests and has accepted reviews
Close if there is no realistic chance of a merge. For example if the authors are not engaged or the branch is very far behind main
Discussions¶
Sowing¶
Ensure it is a discussion
Ensure there is a clear focus
If it is a question, make sure it is well defined
If it is a discussion, suggestion, poll or similar, make sure the topic is clear
Tag community members who can help
Fertilising¶
Check progress
Ask what hasn’t been resolved
Support discussions
Tag community members who can help
Suggest advertising in Slack
Invite to collaboration cafe
Pruning¶
Close discussions when they have concluded
If the discussion is a Q&A, mark an accepted answer
Close as outdated if it is stale