search

cisagov / .github

Default community health files for cisagov
Creative Commons Zero v1.0 Universal
6 stars 11 forks source link

Standardize org-wide labels #7

Open hillaryj opened 3 years ago

hillaryj commented 3 years ago

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. :neckbeard:

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

https://github.com/entrylvl/platform/issues/54

hillaryj commented 3 years ago

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).

jsf9k commented 3 years ago

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 commented 3 years ago

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.

jsf9k commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

jsf9k commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

mcdonnnj commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

dav3r commented 3 years ago

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

hillaryj commented 3 years ago

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

    Screen Shot 2020-11-18 at 11 31 55 AM

  2. Sentence

    Screen Shot 2020-11-18 at 11 32 03 AM
jsf9k commented 3 years ago

The "This issue or pull request":

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 commented 3 years ago

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

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

jsf9k commented 3 years ago

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

fire

hillaryj commented 3 years ago

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

hillaryj commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

hillaryj commented 3 years ago

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.