Define good first issue and clarify help wanted labels

2 files changed, 137 insertions, 8 deletions

diff --git a/contributors/devel/help-wanted.md b/contributors/devel/help-wanted.md
index eb1038a4..a9151c1f 100644
--- a/contributors/devel/help-wanted.md
+++ b/contributors/devel/help-wanted.md
@@ -1,13 +1,140 @@
-# Help Wanted
+# Overview
+
+We use two labels [help wanted](#help-wanted) and [good first
+issue](#good-first-issue) to identify issues that have been specially groomed
+for new contributors. The `good first issue` label is a subset of `help wanted`
+label, indicating that members have committed to providing extra assistance for
+new contributors. All `good first issue` items also have the `help wanted`
+label.
+
+We also have some [suggestions](#suggestions) for using these labels to help
+grow and improve our community.
+
+## Help Wanted
 
 Items marked with the `help wanted` label need to ensure that they are:
 
-- Sufficiently actionable: clear description of what should be done
-- Tractable for new/casual contributors: there is documentation how that type of change should be made
-- Goldilocks priority: Not too high that a core contributor should do it, but not too 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.
-- Up to date: Often these issues become obsolete and have already been done, are no longer desirable, no longer make sense, change in priority, change in difficulty, etc.
+- **Low Barrier to Entry**
+
+  It should be tractable for new contributors. Documentation on how that type of
+  change should be made should already exist.
+
+- **Clear Task**
+
+  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 OP issue, for example: _"The
+  new command syntax is `svcat unbind NAME [--orphan] [--timeout 5m]`"_, with
+  expected validations called out.
+
+- **Goldilocks priority**
+
+  Not too high that a core contributor should do it, but not too 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.
+
+- **Up-To-Date**
+
+  Often these issues become obsolete and have already been done, are no longer
+  desired, no longer make sense, have changed priority or difficulty , etc.
+
+Related commands:
+
+- `/help` : Adds the `help wanted` label to an issue.
+- `/remove-help` : Removes the `help wanted` label from an issue. If the
+  `good first issue` label is present, it is removed as well.
+
+## Good First Issue
+
+Items marked with the `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,
+*decipher prow commands, or identify that their build failed due to a flake.**
+This makes new contributors feel welcome, valued, and assures them that they
+will have an extra level of help with their first contribution.
+
+After a contributor has successfully completed 1-2 `good first issue`'s, they
+should be ready to move on to `help wanted` items, saving remaining `good first
+issue`'s for other new contributors.
+
+These items need to ensure that they follow the guidelines for `help wanted`
+labels (above) in addition to meeting the following criteria:
+
+- **No Barrier to Entry**
+
+  The task is something that a new contributor can tackle without advanced
+  setup, or domain knowledge.
+
+- **Solution Explained**
+
+  The recommended solution is clearly described in the issue.
+
+- **Provides Context**
+
+  If background knowledge is required, this should be explicitly mentioned and a
+  list of suggested readings included.
+
+- **Gives Examples**
+
+  Link to examples of similar implementations so new contributors have a
+  reference guide for their changes.
+
+- **Identifies Relevant Code**
+
+  The relevant code and tests to be changed should be linked in the issue.
+
+- **Ready to Test**
+
+  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!
 
 Related commands:
 
-- `/help` : adds the `help wanted` label to an issue
-- `/remove-help` : removes the `help wanted` label from an issue
\ No newline at end of file
+- `/good-first-issue` : Adds the `good first issue` label to an issue. Also adds
+  the `help wanted` label, if not already present.
+- `/remove-good-first-issue` : Removes the `good first issue` label from an
+  issue.
+
+# Suggestions
+
+We encourage our more experienced members to help new contributors, so that the
+Kubernetes 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 X and
+  then you can use kubectl to    poke around"_, or _"Did you know that you can
+  use fake clients to setup and test this easier?"_.
+- 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.
+
+If you make someone feel like a part of our community, that it's safe to ask
+questions, that people will let them know the rules/norms, that their
+contributions are helpful and appreciated... they will stick around! 🌈
+- Encourage new contributors to seek help on the appropriate slack channels,
+  introduce them, and include them in your conversations.
+- Invite them to the SIG meetings.
+- Give credit to new contributors so that others get to know them, _"Hey, would
+  someone help give a second LGTM on @newperson's first PR on chocolate
+  bunnies?"_. Mention them in the SIG channel/meeting, thank them on twitter or
+  #shoutouts. - Use all the emoji in your approve or lgtm comment. 💖 🚀
+- Let them know that their `good first issue` is getting extra attention to make
+  the first one easier and help them find a follow-up issue.
+- Suggest a related `help wanted` so that can build up experience in an area.
+- People are more likely to continue contributing when they know what to expect,
+  what's the acceptable way to ask for people to review a PR, nudge things along
+  when a PR is stalled. Show them how we operate by helping move their first PR
+  along.
+- If you have time, let the contributor know that they can DM you with questions
+  that they aren't yet comfortable asking the wider group.
diff --git a/contributors/guide/README.md b/contributors/guide/README.md
index ad5cf2e1..d2540117 100644
--- a/contributors/guide/README.md
+++ b/contributors/guide/README.md
@@ -72,7 +72,9 @@ You get the idea - if you ever see something you think should be fixed, you shou
 ### Find a good first topic
 
 There are multiple repositories within the Kubernetes community and a full list of repositories can be found [here](https://github.com/kubernetes/).
-Each repository in the Kubernetes organization has beginner-friendly issues that provide a good first issue. For example, [kubernetes/kubernetes](https://git.k8s.io/kubernetes) has [help wanted issues](https://go.k8s.io/help-wanted) that should not need deep knowledge of the system.
+Each repository in the Kubernetes organization has beginner-friendly issues that provide a good first issue. For example, [kubernetes/kubernetes](https://git.k8s.io/kubernetes) has [help wanted](https://go.k8s.io/help-wanted) and [good first issue](https://github.com/kubernetes/kubernetes/labels/good%20first%20issue) labels for issues that should not need deep knowledge of the system.
+The `good first issue` label indicates that members have committed to providing extra assistance for new contributors.
+
 Another good strategy is to find a documentation improvement, such as a missing/broken link, which will give you exposure to the code submission/review process without the added complication of technical depth. Please see [Contributing](#contributing) below for the workflow.
 
 ### Learn about SIGs