Community: Create "good first issue" label

[jberkus]

The way it is now:

We have the "help-wanted" label, which according to its description should cover issues which are suitable for work by novice contributors. However, that's not how that label is being used; instead, it's being used for issues which are not making progess because they need additional expertise, input, or large time commitments. Mostly, these issues require quite advanced knowledge of Kubernetes. Examples: 60023, 56567.

This means that would-be new contributors, looking for their first place to hack on Kubernetes, can't figure out where to start. We could try to change member's behavior in using the "help wanted" tag, but that seems unlikely to be successful.

What we should do:

1. Add the "good first issue" label to automation and all repos that want it. This includes creating the /good-first-issue and /remove-good-first-issue commands for Prow, and writing a description.
2. Amend the description to the "help wanted" label to reflect its actual use.
3. Share the new label, and an explanation of how "help wanted" and "good first issue" are distinct, with kubernetes-dev, the community meeting and the SIG leads.

The choice of "good first issue" here is because Github has public filters for that label. While other text, such as "for-new-contributors" or "help wanted/easy" might be preferable, I believe that the use of Github's existing label will make things easier for folks who know Github but not Kubernetes.

[cblecker]

/sig contributor-experience

[guineveresaenger]

Is someone working on adding the prow command? I’d like to volunteer for that part if no one’s doing it yet...

[cblecker]

Some thoughts:

• "We could try to change member's behavior in using the "help wanted" tag, but that seems unlikely to be successful." - This shouldn't be a driver. I think we need to set clear guidelines on what "help wanted" should be, and then circulate it far and wide. Same with "good first issue", if we add it.
• I'm in favour of a new "good first issue" label, but only in the case that we can clearly define what the difference is between good first issue, and help wanted. Do they compliment each other? Do they compete with each other? The current definition of help wanted is here: https://github.com/kubernetes/community/blob/master/contributors/devel/help-wanted.md
• I'd like to see that documentation and definition first, before we put the automation or labels into place. My thinking here, is that when we go and trumpet out to people the change to automation (as required by our charter), we can already show them what the automation will be used for before it's turned on.
• Lastly, there's some design decisions around the automation that would need to be made. Should "help wanted" and "good first issue" exist on the same issue? Can you have "good first issue" without "help wanted"? When you remove one, should both go away? Should we use a modifier on the existing /help command.. something like "/help first-issue"?

I'd love to hear thoughts on the above :)

[cblecker]

@guineveresaenger As far as the automation piece, I don't think anyone is working on it. Once we get to the point where we're ready to implement, it's all yours!

[nikhita]

For the documentation of the help-wanted label, we can remove "Tractable for new/casual contributors" from the docs and keep the rest same as it is.

For documenting good first issue:

---

Good First Issue

Items marked with the good first issue label should be tractable for new contributors and need to ensure that they follow the guidelines for help wanted labels (link) and _additionally_ include the following information:

• Mentorship: There should be someone ready to mentor and walk a new contributor through solving the issue. The mentor should mention a way to contact them (slack username, email, etc).
• Clear task: The task is agreed upon and does not require further discussions in the community. The recommended solution is clearly described in the issue.
• Recommended readings: If any prior knowledge is required, this should be explicitly mentioned and a list of suggested readings should be included.
• Examples: If something similar has been implemented before, it should be mentioned to act as a reference for the new contributor.
• Files to update: Point out to the parts of the project that would need to be modified for solving the issue.

Make sure that the issue makes a statement that new contributors are welcome, that they are valued, and that they can start on our project!

---

Example: https://github.com/kubernetes/kubernetes/issues/60538#issuecomment-369182483.

About the automation:

Do they compliment each other? Do they compete with each other?

IMO they compliment each other. I see good first issue as a subset of the help wanted label.

From the above definition, good-first-issue = help-wanted + extra help.

Should "help wanted" and "good first issue" exist on the same issue? Can you have "good first issue" without "help wanted"?

I think we can have a behaviour like this:

• If you have good first issue, you should have help wanted.
• You can have help wanted without good first issue.

When you remove one, should both go away?

• If you have an issue with good first issue and help wanted and:
  
  
  
  • you remove good first issue => good first issue is removed, help wanted stays.
  
  
  • you remove help wanted => both get removed.
  
  
• Additionally, you should be able to add a good first issue label to an issue with an already existing help wanted label.

Should we use a modifier on the existing /help command.. something like "/help first-issue"?

We have two choices here:

1. /help good-first-issue: This makes sense because good first issue cannot exist without help wanted.

However, my only concern is that it is not-so-intuitive. My expectation from the command would be to have a help wanted/good-first-issue, which is not the case. This would (and should) add a new label (since Github treats good first issue as a "special" label).

In this case, removing would be through /remove-help good-first-issue. This is also counter-intuitive.

1. /good-first-issue: I like this one because it is not counterintuitive but I am not sure if it is "logically" correct.

This would mean also mean that the user is surprised that the help wanted label is magically removed. But I guess it is reasonable to expect that?

• /good-first-issue adds good first issue _and_ help wanted.
• /remove-good-first-issue removes good first issue _and_ help wanted.

[nikhita]

From https://github.com/kubernetes/community/issues/860,

Once someone is assigned the issue (either directly or by assigning @k8s-external-contributor), the bot automatically removes the label.

@cblecker Does something like this exist already?

[parispittman]

@nikhita I think explicitly requiring mentorship may deter folks from using the label if they don't have time themselves to handle. I think we should look at it as in - could this person solve this issue by going through our docs, codebase, and limited engagements with the community to figure it out?

I also see good-first-issue as something that implies help-wanted already so needing both would be duplicate, imo. Help-wanted should imply anyone other than a first time contributor because it may be too complex or would most definitely need guidance from another human if you were a first time.

[nikhita]

I think explicitly requiring mentorship may deter folks from using the label if they don't have time themselves to handle.

Fair point, @parispittman. :+1:

[nikhita]

Just noticed that kubernetes/kubectl uses a good first issue already - https://github.com/kubernetes/kubectl/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22.

[jberkus]

@cblecker

"We could try to change member's behavior in using the "help wanted" tag, but that seems unlikely to be successful." - This shouldn't be a driver. I think we need to set clear guidelines on what "help wanted" should be, and then circulate it far and wide. Same with "good first issue", if we add it.

In 20 years of open source development, I've found that you only attempt to change people's habits when there's a large benefit to be delivered thereby. It's very, very hard to do.

[jberkus]

Seems like we have a definitinion for this and no real objections. Is there anything blocking moving foward (PR and kubernetes-dev discussion)?

[cblecker]

@jberkus No, I don't think so!
Suggested path forward:

• PR to k/community updating the help-wanted.md with the proposed definitions
• Send PR to k-dev with a timebox for feedback/consensus
• PR to k/test-infra to add the label
• PR to k/test-infra to add the command

[k8s-ci-robot]

@parispittman: GitHub didn't allow me to assign the following users: carolynvs.

Note that only kubernetes members and repo collaborators can be assigned.

In response to this:

/assign @carolynvs

/cc

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[parispittman]

/cc

[cblecker]

To update this, the label was created as a part of https://github.com/kubernetes/test-infra/pull/8129.
We still need to:

• update our "help wanted" guidelines with what the policy should be
• update the /help bot command to allow this label to be applied

@nikhita @guineveresaenger @jberkus: You all had expressed interest in this issue. Does anyone want to tackle one or more of these pieces in, say, the next two weeks? I'd like to move the needle forward on this. I'm happy to provide reviews/mentoring. If you don't have the cycles, that's okay too (although letting me know would be appreciated).

[carolynvs]

I would like to contribute to the "help wanted" guidelines! I had pneumonia the past few weeks, but am finally back to work and can share some of what I've been doing with SIG service catalog to bring in new contributors.

[carolynvs]

@guineveresaenger @nikhita I would love to collaborate with you both on some guidelines for help-wanted and good-first-pr. What do you say? 😀

EDIT: I just caught up on https://github.com/kubernetes/community/issues/1959#issuecomment-375687541 and that really encompasses the majority of how I use those labels today:

• good first pr is a subset of help wanted and all good first pr issues are also labeled with help wanted for easier filtering
• Stick with the familiar GitHub labels and encourage other maintainers to use different ways to ask for help on a difficult issue.
  
  
  
  • We use the needs-help label for issues that we are stuck on.
  
  
  • We regularly look for those issues during grooming and raise pertinent ones up in our weekly agenda to ask for volunteers.
  
  
• Before flagging something withhelp wanted it should meet the following criteria:
  
  
  
  • It is something that someone without deep domain knowledge can tackle without extensive clarification or assistance.
  
  
  • The desired change has been clearly explained in the OP issue.
  
  
  • API / CLI behavior is decided and included in the OP issue. e.g. The new command syntax is svcat unbind NAME [--orphan] [--timeout 5m] with expected validations called out.
  
  
  • Call out if new tests are needed (and where a good test to follow exists already) or should be changed.
  
  
  • Identify the general area of the code that needs to be changed, and include helpful suggestions on a possible implementations, related code that demonstrate similar techniques, etc.
  
  
• Before flagging something with good first pr it should meet all of the help wanted criteria in addition to following criteria:
  
  
  
  • It is something that a new contributor can tackle without advanced setup, or domain knowledge.
  
  
  • The issue should be extremely well-defined and limited in scope so that there no unexpected changes that come up during a review.
  
  
  • There should be existing tests that can be modified, or existing test cases copied and tweaked. If the area of code doesn't have existing tests, add a fixture first (hey! That's a great help wanted).
  
  
  • The relevant code and tests should be linked in the issue.
  
  
• We encourage experienced contributors to leave the good first pr issues for new contributors. After they have completed 1-2 good first prs, they should move on to the help wanted's.
• Maintainers keep an eye on the good first pr PRs and help move them through the process so that the new contributor isn't left to decipher prow commands, build flakes, finding an approver, begging for reviews, etc.
• Reviewers are encouraged to provide extra assistance during their reviews to help answer questions, point out notable things (like "hey one way to reproduce this in a cluster is to do this and then you can use kubectl to poke around", or "Did you know that you can use Fake Clients to setup and test this in an easier way?", etc). The goal is to help them learn enough about setting up an env, running tests, and navigating this area of the code so that they can tackle a related help wanted issue next time.
• Encourage new contributors to seek help on the slack channel, introduce them and include them in your conversations. Invite them to your SIG meetings.
  
  
  
  • I often reach out in a DM to provide extra info on what to expect ("oh everyone is at a conf this week, so don't take it personal if your PR takes a bit to get a review"), explain what I am doing to move a PR along so that they know what they can do for their next one, or encourage them to ask questions that they aren't comfortable asking in the larger slack channel.
  
  
  • Let them know that their good first pr is getting extra attention to make the first one easier and help them find a follow-up issue, maybe a related help wanted so that they have traction after that first PR. People are more likely to keep contributing if they know what to expect, what's the acceptable way to ask for people to review a PR, nudge things along when people forget about their PR, etc.
  
  
  • Give credit to new contributors where you can so that people get to know them, "Hey can someone help give a second LGTM on @newperon's first PR on chocolate bunnies?". Mention them in the SIG channel/meeting, thank them on twitter or #shoutout. Use all the emoji in your approval LGTM comment. 💖 :rocket:
  
  

I realize that this is a wall of text but really it all comes to to this:

If you make someone feel like a part of the group, that it's safe to ask questions, that people will let them know the rules/norms if they forget, that their contribution was helpful and appreciated... they will stick around! 🌈

[nikhita]

@carolynvs the edit is :100:

update the /help bot command to allow this label to be applied

I'd like to work on this! I'll get started with it. @cblecker, I'll ping you in case I need help. :)

[carolynvs]

I'll work on combining the ideas here and submit a PR with changes to the doc files in this repo for the help wanted and good first pr labels.

[guineveresaenger]

Hi everyone- just woke up and see that everything is being volunteered for. I’ve been swamped lately so I’m happy to review and observe! Thank you all!

[nikhita]

@guineveresaenger would love a review of https://github.com/kubernetes/test-infra/pull/8273 :)

[nikhita]

Trying out something for checking the labels automation:

/label approved

[nikhita]

/reopen

Docs PR still open: https://github.com/kubernetes/community/pull/2226

[k8s-ci-robot]

@nikhita: you can't re-open an issue/PR unless you authored it or you are assigned to it.

In response to this:

/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[nikhita]

/assign

[nikhita]

/reopen

[cblecker]

Last piece: Communicating what we've done! Who would like to send the e-mail to k-dev pointing at the docs as well as the bot commands?

[nikhita]

Who would like to send the e-mail to k-dev pointing at the docs as well as the bot commands?

I'll do it! :tada:

I'll send the email on Monday. I'll sync up with @carolynvs and @guineveresaenger before hitting send. :)

[nikhita]

Kubernetes-dev: https://groups.google.com/d/msg/kubernetes-dev/UTkiFncx0YI/jZ45qIB_BQAJ
SIG-contribex: https://groups.google.com/d/msg/kubernetes-sig-contribex/-59Zu7LwBcA/f0lcQfGABQAJ

[guineveresaenger]

All work in this has been completed. Thank you everyone!

/close