Standardize org-wide labels

[hillaryj]

From PR #4, continuing discussion on labels.

We want to standardize on a set of labels org-wide for cisagov.

Individual repos can then add additional labels if needed.

From @jsf9k:

@cisagov/team-ois, I created example labels in this repository. Please have a look and let me know if you think those are good enough to make official here.

From @felddy:

I'd prefer more emojis in the labels... but these are fine.

https://github.blog/2018-02-22-label-improvements-emoji-descriptions-and-more/

entrylvl/platform#54

[hillaryj]

Another approach might be to separate out the different types of labels, e.g. status labels vs. type labels.

One librarian-esque approach that is still simple is described in this article on Sane GitHub Labels. This also links to a tool that makes label management easier.

Personally, I'd prefer to break out feature or improvement into its new vs updated parts - and also I have a strong preference for brevity and specificity in labels. So, something like the following (with or without the emoji).

• 🎉 feature for new features and functionality
• 🛠 improvement for improvements to existing functionality

[jsf9k]

I merged feature and improvement because I often have a difficult time deciding which is correct. Often my changes greatly expand the functionality of an existing feature.

I'm not greatly opposed to separating them again, if others find that useful.

[hillaryj]

I agree that Feature is sort of vague - I'll think about a better name for it. Or maybe it's just unnecessary.

Thinking about it more, adding status labels duplicates the purpose of the project boards, so since theoretically we use that for tracking statuses, unless we added automation it would require extra/duplicate effort.

So, for type labels, here's a proposed list with some alternate names. For repos like cool-system and cyhy-system we'd want to add a label for epics, since they have more project management than most - or, that could be a standard.

• blocked
• breaking change
• bug
• documentation
• duplicate
• epic
• improvement (alt: enhancement)
• invalid
• need info
• question
• upstream change (alt: maintenance or dependencies)
• version bump
• wontfix

[jsf9k]

Does ZenHub require an "eipc" label? Does it auto-add one for you?

I'd prefer to add the "epic" nowhere or add it everywhere. I get that there will be rare repos that need one or more custom labels, but "epics" seem to be generally useful unless that labeling is already being handled (perhaps by a means other than repo labels) in Zenhub.

I like the list @hillaryj created above. It's pretty similar to what I came up with, plus a few additions. I prefer the names @hillaryj listed over the alternatives she provided, which I think are more vague.

[hillaryj]

Roger that - I'd add epic everywhere, then. ZenHub doesn't require it, but it's a useful category for project management.

I definitely worked from that list - thanks for starting us off!

[jsf9k]

For the record, I'm fine with adding emojis if someone wants to take the lead on that.

[jsf9k]

I edited the labels for this repository to agree with Hillary's list, but I didn't delete "help wanted" or 'good first issue" yet. I feel we could go ahead and delete them since we never use them, although at one point we discussed using those labels to try and lure in external contributors.

Thoughts?

[dav3r]

I edited the labels for this repository to agree with Hillary's list, but I didn't delete "help wanted" or 'good first issue" yet. I feel we could go ahead and delete them since we never use them, although at one point we discussed using those labels to try and lure in external contributors.

Doesn't matter to me either way- it doesn't bother me having unused labels that we may or may not use in the future.

[hillaryj]

I'm fine with leaving them in - we're much more likely to use them if they exist already.

If we want to integrate with code.gov's "open tasks" to lure external contributors, we'll also need to add a code.gov label. The good first issue label will help there as it gets pulled in as a type in the open tasks list.

[jsf9k]

Added the "code.gov" label and left the "good first issue" label in place. I think we can remove "help wanted" with the addition of "code.gov". I believe that the set of labels is good now. Going once...

[hillaryj]

To capture for posterity, here's what we currently have - let's flesh out the descriptions a bit (specifically epic):

["blocked"]
color = "eb6420"
name = "blocked"
description = "This issue or pull request is blocked"

["breaking change"]
color = "000000"
name = "breaking change"
description = "This issue or pull request will cause existing functionality to change"

["bug"]
color = "d73a4a"
name = "bug"
description = "This issue or pull request addresses broken functionality"

["code.gov"]
color = "07648d"
name = "code.gov"
description = "This issue will be advertised on code.gov's \"Open Tasks\" page (https://code.gov/open-tasks)"

["documentation"]
color = "5319e7"
name = "documentation"
description = "This issue or pull request involves improvements or additions to documentation"

["duplicate"]
color = "cfd3d7"
name = "duplicate"
description = "This issue or pull request already exists"

["epic"]
color = "b005bc"
name = "epic"
description = "This issue is an epic"

["good first issue"]
color = "0e8a16"
name = "good first issue"
description = "Good for newcomers"

["improvement"]
color = "a2eeef"
name = "improvement"
description = "This issue or pull request will add new or improve existing functionality"

["invalid"]
color = "fef2c0"
name = "invalid"
description = "This doesn't seem right"

["need info"]
color = "a4fc5d"
name = "need info"
description = "This issue or pull request requires further information"

["question"]
color = "ef476c"
name = "question"
description = "Further information is requested"

["upstream update"]
color = "1d76db"
name = "upstream update"
description = "This issue or pull request relates to pulling in upstream updates"

["version bump"]
color = "d4c5f9"
name = "version bump"
description = "This issue or pull request involves a version bump"

["wontfix"]
color = "ffffff"
name = "wontfix"
description = "This issue will not be worked on"

[jsf9k]

Are "question" and "need info" redundant? They feel redundant to me.

[mcdonnnj]

So I have apprehensions about using terms like epic. Someone unfamiliar with commercial Agile processes may be unfamiliar with the term, and someone familiar may be thrown off by the lack of any related labels (story, etc). Explaining to an on-boarding team member is something we can readily cover, but for an outsider looking into our projects and processes it may be confusing or misleading.

[mcdonnnj]

Are "question" and "need info" redundant? They feel redundant to me.

I think question is about an issue that is a question, whereas I would use need info on a bug report where the submitter hasn't given me enough information to work on to resolve.

[jsf9k]

I think question is about an issue that is a question, whereas I would use need info on a bug report where the submitter hasn't given me enough information to work on to resolve.

I updated the description for the "question" label to try to capture this distinction. What do you think @mcdonnnj?

[mcdonnnj]

I think question is about an issue that is a question, whereas I would use need info on a bug report where the submitter hasn't given me enough information to work on to resolve.

I updated the description for the "question" label to try to capture this distinction. What do you think @mcdonnnj?

I think the updated description gives good distinction between the purposes/differences between the two.

[jsf9k]

Have we reached a local maximum on these labels? Should we move forward with what we have or continue thinking them over?

[dav3r]

I say ship it- we can always tweak them later if we identify a need.

[hillaryj]

Do y'all have a preference stylistically for the descriptions, considering that they generally show up as hover text?

I prefer them to be partial sentences without "This issue or pull request" but I'm good with whatever the team decides.

Examples:

1. Declarative fragment

2. Sentence

[jsf9k]

The "This issue or pull request":

• Makes the types of thangs to which the label applies explicit
• Gives me the opportunity to specify only "This issue" or only "This pull request" for the cases where the label only applies to one or the other - admittedly there are only a couple of these cases

I'm OK with removing the "This issue or pull request" as long as we specify "(issues only)" or "(pull requests only)" where applicable, but my preference is to include the "This issue or pull request".

[hillaryj]

That seems reasonable to me - I've run my label updater shebang on this repo and the dev guide:

• https://github.com/cisagov/.github/issues/labels
• https://github.com/cisagov/development-guide/issues/labels

If there are no other objections/alterations, I'll let 'er rip on the rest

[jsf9k]

If there are no other objections/alterations, I'll let 'er rip on the rest

[hillaryj]

Will finish with the label roll-out after the holiday and write it up. 👍🏻

[hillaryj]

I updated the default labels here: https://github.com/organizations/cisagov/settings/repository-defaults and I'm working through the repos to make sure I don't strip out labels folks are using.

[hillaryj]

Labels have been updated! Certain labels were excluded from this, mostly in repositories that have been archived or that are used by other groups in CISA and have specialized labels and/or labels already in use that would be destroyed and the references lost.

Dependabot uses a default label of "dependencies" when it makes PRs. We can override that behavior in the dependabot.yml files (i.e. by updating the skeletons) if we wish and have it specify the upstream updates label we just instituted. If we do nothing, from what the docs say, Dependabot will re-create the dependencies label the next time it puts in a PR in a specific repository.

I've got some documentation on how I did this process and will be adding it to the development guide. I'll link here and close the issue once that is done.

[hillaryj]

If you go looking for a label that no longer exists, each PR and issue still records that it was once labeled that.

If you sort by "last updated", then the label removals will float to the top.

For cool-system issues, for example: https://github.com/cisagov/cool-system/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc

[dav3r]

@hillaryj What work is left to do for this issue?

[hillaryj]

I have a PR to make with the labels config file and a doc on how to run the process, ETA Monday. I'll link it here.