Labeling of Issues for New Contributors and GitHub Conventions

[jzf2101]

Having just run a 4-hour mini sprint, I have noticed that GitHub uses the labels help wanted and good first issue in a new feature which searches for issues for new contributors. See screenshot below:

What do we think about switching our new contributor type labels to this convention for improved search engine optimization?

I think making the switch would be preferred since we want to make it clear which issues are appropriate for new contributors. At the same time, I understand this would change our labeling conventions by team and that this should be considered on a repo-by-repo basis.

[blink1073]

+1 for changing.

[Carreau]

+1 to have something standard, if it's what GitHub is promoting, even greater.

I'm going to assume "help wanted" issue might be tougher than "good first issue".

[willingc]

+1 to using both. We're already using "help wanted" on all the jupyterhub repos. Although it's difficult to determine what makes a "good first issue" in my experience, it's worth giving that a shot too.

[jzf2101]

Related, I made a list of major repos with new contributor type issues on the PyCon Canada sprint wiki page:

https://github.com/pyconca/2017-wiki/wiki/Sprints#project-jupyter

[damianavila]

+1 on the change.

[takluyver]

+1 to using Github's standard labels for these things

[jasongrout]

+1 for using standard GitHub labeling.

[jhamrick]

+1 for standard labeling too.

[gnestor]

+1

[fperez]

+1, this is the kind of standardization that wins by more projects adopting. Given we have a crazy number of orgs/projects, we can benefit from this while simultaneously helping it become adopted. Thanks @jzf2101!

[jzf2101]

I'm assuming we're of agreement and will start making appropriate proposed changes to the repos on the issues.

[willingc]

Thanks @jzf2101.

[jasongrout]

Can we give guidance on when help wanted is an appropriate label? I've been using good first issue on a decent number of issues. I imagine most issues (in the ipywidgets repo) could be labeled help wanted.

[jasongrout]

Ah, I see @jzf2101 did put some guidance at https://github.com/jupyter/governance/pull/29/commits/a0a9dae520f8999b9b8be17790c88ba69cbe65a2#diff-722dd620d03a6eae1147461b0b46df10R131:

Across GitHub, good first issue is the common label for beginner-friendly issues. help wanted indicates interest in external help from the community on an issue.

[jasongrout]

I consider most every issue to be help wanted. My fear is that if I don't put this on an issue, the takeaway is that help is not wanted.

I'll probably just tag most everything as help wanted under this guidance.

[takluyver]

Yeah, I'm not exactly sure when 'help wanted' makes sense.

Maybe we should use it to mean that we don't plan to work on it ourselves, but:

• It's not something that a beginner could easily tackle (that would be good first issue)
• We think it's an actual bug or feature request that makes sense (not user confusion or a weird problem with their system)
• We would accept a pull request to close the issue, assuming it meets our standards.

[willingc]

@takluyver's bullets make sense about how help wanted is used on many other projects.

[jasongrout]

Thanks @takluyver. I've been using milestones to separate out actual work items ("Future" or a specific release milestone) from user confusion/questions ("Reference" milestone).

I like how you phrase things, but I'll probably also put help wanted on good first issue issues too - it's really hard sometimes to tell the difficulty, and I see good first issue as a subset of all help wanted issues. Does that make sense?

[willingc]

I see good first issue as a subset of all help wanted issues. Does that make sense?

Yes :-)

[takluyver]

That's fine by me. So to summarise:

• help wanted means there's something identified to do, but the core team is not about to do it.
• good first issue means the same, plus we think the task is relatively easy for a new contributor to try to tackle.

[jzf2101]

@takluyver I also think it would be useful to suggest that it's something identified to do which the core team would like an additional contributor to work on who is not a core maintainer? As in we'd like to reserve this issue for other contributors

I'm stating this to distinguish the help wanted label from the won't fix label based on GitHub's conventions

[willingc]

I would highly recommend not using won't fix even though it comes as a GitHub default since it discourages outside and new contributors. It's better to simply state that it's not in the scope of the project roadmap, close, and label as reference See rationale from Ian Bicking http://www.ianbicking.org/blog/2014/03/use-github-issues-to-organize-a-project.html

An aside: the labels duplicate, wontfix, and invalid are (a) unnecessary, and (b) socially dangerous. If something is a duplicate you can close it with the comment “Dup of #123”. Often that’s not exactly what happened though, you might say “rendered moot by #123” or “once #123 is fixed this won’t be an issue” or something specific. And wontfix is the worst, ...

[jzf2101]

@willingc i agree - i'm just trying to be explicit about how help wanted is different from won't fix

[takluyver]

won't fix is more like 'no', rather than 'ok if someone else does it'.