Codifying Standards for issues labeled "Good First Issue"

[bnb]

I recently shared a link to all the issues labeled with "Good First Issue" on twitter, encouraging individuals to see it as a path to start contributing to the project if they're interested in doing so.

One individual stood out–they said they would love to tackle some of the issues with a class they were teaching with about 50 students.

They reached out to me again pointing out some barriers presented in issues labeled "Good First Issue". These are legitimate barriers–and seem like they could be extremely off-putting to newcomers trying to engage in issues we've explicitly labeled "Good First Issue".

I'd like to propose that we codify a standard that issues labeled "Good First Issue" are held to.

While I definitely think this could be a good effort for the CommComm, I think that the TSC will probably be more invested in the outcome of doing this.

Thoughts?

[humphd]

This is great: I think deciding what you mean by "Good First Issue" is really helpful, since there isn't one way it gets applied. In my experience having students fix these on lots of open source projects, I've found the ones that tend to work best are those where you are able to make a clear determination about what the bug is (e.g., no controversy about whether this issue is real), and how it should be fixed (e.g., "Here's how you'd go about fixing this...").

A lot of projects use "Good First Issue" as a rating, to indicate "this is easy." Others use it as a proxy for "I don't have time to fix this." However, both can (and do) lead to people flagging controversial changes that end up being closed when someone attempts the fix, or mean that people asking for help are ignored because no one really wants to commit to the change/fix after all.

I've written about this previously http://blog.humphd.org/why-good-first-bugs-often-arent/

Thanks for trying to make this work. It's great that node is making an effort to find footholds for new people to begin climbing.

[bnb]

Forgot to mention the TSC and CommComm: @nodejs/tsc, @nodejs/community-committee.

[Trott]

Problems I've had with this label in the nodejs/node repo:

• The issue often gets snapped up quickly by someone who already has contributions in the project. So instead of an entry point for a new person, it becomes the "easy" task list for someone who will get it done faster than a new person can get node cloned and compiled, thus defeating the purpose of the label. (When I see this, I often politely request that people stop doing that.)

• Unclear whether the label should be applied to good first contributions for people with no specialized knowledge or if it's a good first contribution for (say) someone who really knows about Makefiles or crypto or something like that.

• Often see a problem with someone saying they're going to work on it and then disappearing. This discourages others from picking it up.

• Sometimes multiple folks work on an issue that's been labeled. Then we have to pick one person's PR and apologize to other people.

• There's a tendency to label documentation things as good first contributions, perpetuating our mediocre standards for documentation. We have a lot of room for improvement in docs, but almost none of it is "good first contribution" stuff unless you're talking about a good first contribution from someone who has some experience as a professional technical writer and/or UX designer. Unpopular opinion: Documentation should almost never be listed as a good first contribution. Maybe make an exception for simple spelling corrections and things like that (on the grounds that the actual fix is not the interesting part there but that the user still gets to go through the cloning/compiling/PR/review process which is important). Writing more than a sentence or two of new documentation text is almost never a good first contribution unless it's someone who is especially skilled at documentation-writing.

[WaleedAshraf]

Agree with all of @Trott points.

My thoughts:

• Can we put a limit on who can pick the GFI (good first issue)? Like if I have X (lets say 5) number of PRs merged into that repo, I can't take a GFI anymore. IMO GFI is for those who have less than X (5) contribution to that project.

• When I'm looking at the list of GFI, I mostly open those which have fewer comments:

Because more comments mean there is already work going on on that one. But few times, I have found that there was a discussion on the issue, months ago and then there is no further development.

• Can we put minimum resolution time of GFI? Every issue which is tagged as GFI, add a comment at the end like, "Inform here before starting on this issue". And then after X (lets say 3) days, if there is no reply/PR, that issue is again open everyone to fix.

• Can we introduce tags like "Taken" / "Not Taken"? IMO at least one maintainer/collaborator is watching a GFI. And if he/she sees no further development after X days, he may switch tags to "Not taken". This way, anyone can easily filter issue with tags => GFI + "Not taken".

[joyeecheung]

We can use the "in progress" label for good first issues so people know if it's taken or not. Also IMO they are good first issues so they should be fixed by first-time contributors , which are easily identifiable via their GitHub status.

[gr2m]

I second that first-time issues should be reserved for first-time contributors only. Secondary issues with the goal of retention should be different in my experience, they are usually harder to get right, but it’s maybe out of scope of the discussion at hand?

We use "available" and "in progress" to show state on labels. Once created, we usually give people a day or two to express interest, but also make clear that we’d only like people to signup if they will be able to start working on it within a day or two.

For super simple issues, I suggest that everyone can send separate pull-requests and I’ll review them all, so folks can exercise sending a pull request as for many the process is what’s keeping them from contributing.

For more complex issue, I suggest that folks collaborate together on the issue :)

I like the idea of defining some requirements for using the "good first issue" issue. For super-duper simple issues, we use a template like this at Hoodie: hoodiehq/camp#137 (these are created automatically and meant for overall first-time Open Source contributors). For more complex issues we use a template like this: hoodiehq/camp#106. @Roshanjossey wrote a blog post about it a while back https://medium.com/@roshanjossey/how-better-issues-improve-collaboration-5a4e6ff95e90. It is nice to elaborate a bit on the context of the issue for new contributors as they often times don’t know much about the project yet. It also sends a clear message that new contributors are welcome, appreciated and it gives an opportunity to set a friendly tone for people who interact with the project for the first time.

One requirement could be to say that the "good first issue" should require one or multiple assigned mentors?

[ljharb]

Since new contribs may need to build their confidence for some time, perhaps only allowing them one of these ever might be a bit strict?

[joyeecheung]

I like the idea of assigning mentors to good first issues. Usually if it's a collaborator who opens the issue and labels it themselves they would be the people mentoring, but some issues are labeled by people who are not previously in the disucussion. We can require that whoever labels it should assign that issue to a mentor first. If someone wants to label it but cannot be a mentor themselves they should look for one in the thread before labeling the issue.

We should also document these things so people who want to get started can understand the conventions that we have and what they can do to make the coordination more effective. This would be different from our current contributing guide which also targets people who submit a fix or an enhancement because they need it, in that case they usually already have a PR ready to be submitted.

[joyeecheung]

@ljharb

Since new contribs may need to build their confidence for some time, perhaps only allowing them one of these ever might be a bit strict?

In that case we should get a new label for good second, third, etc. issues. Good first issues should be simple tasks that would not incur too much friction that disheartens a new contributor, but you don't really get to learn more if you do it again. Once they understand the process by following through the first PR, they would be more ready to tackle harsher reviews, and can learn more by fixing a more advanced issue.

[mhdawson]

Adding to @joyeecheung comments as I read through the discussion I was also thinking we needed additional labels. I think we'd want to limit to a smallish set like:

• good first issue (if you have 0 commits)
• good new contributor issue (for example if you have less than 5 commits)

I also agree that documenting makes sense, along with the ask that people don't grab issues tagged with these tags after they are no longer a "first" or "new" contributor.

[Qard]

It might be beneficial to have good-first-issue tied to a mentor. When someone wants to claim that issue, they can @ mention a mentors team and someone on that team could then volunteer to guide them through their first commit.

[joyeecheung]

I have given this a bit of thought today, and here is what I have in mind:

1. good first issue
   • For people who have 0 commits
   • Should need no more than 3 rounds of reviews to land, and fast-trackable.
   • They should either be assigned to mentors, or come with specific instructions.
   • This is intended for people who are not familiar with the PR process or the environment setup.
   • Some examples could be: broken links or typos in docs, test refactoring, error message improvement (for errors with permanent codes), adding comments to tests, basically what we do in code-and-learns.
   • What they will learn: general structure of the code base, how to build and test the project, some necessary git skills, how our PR process work including base branches, commit message formats, CI runs, review process, etc.
2. good second issue (I still prefer this name in case people mistake it with good first issue)
   • For people who have < 5 commits
   • May need more than 3 rounds of reviews, and usually are not fast-trackable.
   • They must have mentors assigned.
   • This is intended for people who are already familiar with the PR process and want to face the challenge and are not likely to be disheartened by the process. (For example, they will not have trouble with git rebase, or submit a patch with commit message that does not comply to the guidelines at all, or target the wrong branch...things that distract them from the actual code changes)
   • Examples: migrating V8 deprecated APIs (e.g. V8: upcoming deprecation warnings node#18909), feature requests that are easier to implement, docs that need a significant change and requires technical writing skills (what @Trott mentioned in Codifying Standards for issues labeled "Good First Issue" #50 (comment)).
   • What they will learn: more advanced knowledge about the code base, our coding conventions and the consensus seeking process (should there be any different opinions during the review).

[mhdawson]

@joyeecheung's proposal looks good to me.

[cjihrig]

@joyeecheung's proposal SGTM as well.

[Trott]

Closing stuff that has been inactive for more than a year in this repo, but if someone plans on picking this up, just go ahead and re-open! No strong opinions from me. Just tidying.