We use two labels Status: Help Wanted and Status: Good First Issue to flag issues that have been identified as well-suited for community contributors. The
Status: Good First Issue label is a subset of
Status: Help Wanted label, and indicates that project members have committed to providing extra assistance for new contributors. All
Good First Issue issues also have the
Help Wanted label applied.
We also have some suggestions for using these labels to help grow and improve our community.
Chef’s core projects also have tools to help expose these issues in a meaningful way: - Chef First Issues - [Habitat First Issues] - [InSpec First Issues] - [Automate First Issues]
Issues marked with the
Status: Help Wanted label need to ensure that they are:
It should be tractable for external contributors who don’t have 100% context on a project. Documentation on how that type of change should be made should already exist.
The task is agreed upon and does not require further discussions in the community. Call out if that area of code is untested and requires new fixtures.
API / CLI behavior is decided and included in the original issue, for (a completely fabricated and unrealistic) example: “The new command syntax is
hab origin duplicate NAME [--url] [--auth <some_key>]“, with expected validations called out.
Not too high that a core contributor should do it, but not so low that it isn’t useful enough for a core contributor to spend time to review it, answer questions, help get it into a release, etc.
Often these issues become obsolete and have already been done, are no longer desired, no longer make sense, have changed priority or difficulty, etc. Project members are encouraged to groom the backlog of
Help Wanted issues on some regular cadence.
Issues marked with the
Status: Good First Issue label are intended for first-time contributors. It indicates that members will keep an eye out for these pull requests and shepherd it through our processes.
New contributors should not be left to find an approver, ping for reviews, or identify that their build had a transitive or irreproducible failure. This makes new contributors feel welcome, valued, and assures them that they will have an extra level of help with their first contribution.
These issues need to ensure that they follow the guidelines for
Status: Help Wanted labels (above) in addition to meeting the following criteria:
The task is something that a new contributor can tackle without advanced setup, or domain knowledge.
The recommended solution is clearly described in the issue.
If background knowledge is required, this should be explicitly mentioned and a list of suggested readings included.
Link to examples of similar implementations so new contributors have a reference guide for their changes.
The relevant code and tests to be changed should be linked in the issue.
There should be existing tests that can be modified, or existing test cases fit to be copied. If the area of code doesn’t have tests, before labeling the issue, add a test fixture. This prep often makes a great
Help Wanted task!
We encourage our more experienced members to help new contributors, so that our community can continue to grow and maintain the kind, inclusive community that we all enjoy today.
The following suggestions go a long way toward preventing “drive-by” PRs, and ensure that our investment in new contributors is rewarded by them coming back and becoming regulars.
Provide extra assistance during reviews on
Good First Issue pull requests:
- Answer questions and identify useful docs.
- Offer advice such as “One way to reproduce this in a cluster is to do use docker compose then you can use curl to poke around”, or “Did you know that you can use fake clients to setup and test this easier?” etc.
- Help new contributors learn enough about the project, setting up their environment, running tests, and navigating this area of the code so that they can tackle a related
Help Wanted issue next time.
Good First Issue, let them know their PR is getting extra attention to make the process easier. Additionally, once the PR is merged, help them find a follow-up issue.
Help Wantedissue so that they can build up experience in an area.