Update Issue Triaging Labels to reflect the improved process

[aaronshurley]

Describe the problem/challenge you have We recently updated the issue triage process to publicly define the process and to make prioritization decisions more transparent. Additionally, this updated process introduced a new set of priority labels which use a new label format: <category>/<category-option (ex: priority/important-soon.

In order to bring all of our primary repos into alignment with this new process, we should ensure that our labels are updated and sufficient.

The primary audience for these changes is the maintainers since we use the labels for triaging and prioritization.

Describe the solution you'd like Acceptance Criteria:

1. The primary repos have a consistent set of labels and github-actions are updated to reflect them

Anything else you would like to add:

• The priority labels should already be in our primary repos.
• We could use this time to align on the dashes vs spaces argument. The latest context on why dashes are preferred is because it better supports the slash-separated schema and follows how k8s uses labels.
• Using k8s as inspiration, perhaps we update our triage-related labels (such as needs-triage,triage/accepted, or kind/*).

[aaronshurley]

Moved this to accepted as it supports our updated issue triage process. Open for feedback if there are alternative suggestions.

[aaronshurley]

Discussed with ytt/kbld/imgpgk folks and estimated this as a 1.

[aaronshurley]

As a high-level proposal for our labeling scheme:

• prioritization
  • priority/critical-urgent
  • priority/important-soon
  • priority/important-longterm
  • priority/unprioritized-backlog
  • priority/awaiting-more-evidence
• kind
  • kind/enhancement
  • kind/bug
  • kind/cleanup # eng-focused/non-feature work
  • kind/documentation
  • kind/discussion
  • kind/support
  • kind/dependencies # mostly dependabot bumps
• triage
  • triage/accepted # replaces carvel-accepted
  • triage/needs-information
  • triage/duplicate # we would label this, link to the original issue, and close
• needs something
  • needs-triage # replaces carvel-triage
  • needs-kind # maybe we don't need this yet but would be helpful automation in the future
  • needs-prioritization # maybe we don't need this yet but would be helpful automation in the future

[pivotaljohn]

I think of:

• documentation as a "component" of the product rather than a sort/kind of change.
• discussion as a kind of "state" — this issue is currently under discussion and progress is paused.
• dependencies as an enhancement that happens to be automatically generated.
• cleanup suggests to me a kind of reactive stance... is this kind of work "operations"? meaning things we need to do to (more efficiently) produce enhancements, fix bugs, provide support?
• if an issue makes it past triage, it is implied "accepted" otherwise it would have been closed.

Suggestion:

• prioritization
  • priority/critical-urgent
  • priority/important-soon
  • priority/important-longterm
  • priority/valuable-whenever
• kind
  • kind/enhancement # includes dependabot bumps
  • kind/bug
  • kind/support
  • kind/ops # eng-focused/non-feature work
• component
  • component/core
  • component/documentation
  • component/(tools-specific: plugins, playground, etc.)
• state
  • state/in-triage # initial state (needs: kind and prioritization); if more info required, add "blocked/needs-information"
  • state/duplicate
  • state/in-discussion # all information is available, but issue requires further evidence and dialogue
  • state/out-of-scope # triaged to be outside the scope of the product's charter
  • state/accepted # has kind and prioritization and is available to be worked on by anyone.
  • state/committed # maintainer team commits to doing this work
  • state/in-progress
  • state/needs-review
  • state/done
• blocked
  • blocked/needs-information # need input/data/information from someone outside maintainer teams
  • blocked/waiting-on-others # cannot continue until work from another group is finished

Acknowledging this is rather divergent from the original proposal.

In an effort to make a connection to what's been proposed, here's an attempt at mapping some concepts from the original:

• priority/awaiting-more-evidence ==> state/in-discussion
• kind/cleanup ==> kind/ops
• kind/documentation ==> kind/enhancement + component/documentation
• kind/dependencies ==> kind/enhancement (maybe create a component? + component/dependencies)
• triage/accepted ==> state/accepted
• triage/needs-information ==> state/in-triage + blocked/needs-information
• triage/duplicate ==> state/duplicate
• needs-triage ==> state/in-triage
• needs-kind ==> state/in-triage (+ blocked/needs-information)
• needs-prioritization ==> state/in-triage (+ blocked/needs-information)

[aaronshurley]

@pivotaljohn Love these thoughts! You bring up a lot of great points and suggestions. To build off of your suggestions, I have some thoughts:

• As general guidance, I view these labels to serve the team of maintainers as the primary target persona. I'm hoping that we can establish a minimum set of labels in order to streamline our ability to prioritize and schedule work to be done.
• priority
  • priority/valuable-whenever. To me, "valuable-whenever" feels a bit too vague and may be difficult to relatively compare it to the other options (such as "important-longterm"). I still prefer something that states that the maintainers are not planning to schedule this work soon. "unprioritized-backlog" captures that well enough for me. "valuable-but-unprioritized" feels a bit wordy and with this set of labels, I don't think that anything "not valuable" will persist in our list of issues.
  • If we strive to set priority and kind labels for every issue, I think we need a "priority/awaiting-more-evidence" option to show that this is not yet a priority because we need more information (i.e. from the requester or considering product fit). However, we could maybe just use the "blocked" labels to signify why a priority is not yet assigned.
• I like the reduced set of kind options.
• I'm wondering if we can do away with the component labels? I'm not sure if this adds much value and I'd like to minimize overhead.
• state
  • I prefer "needs-triage" to "in-triage". "in-triage" feels like an active state to me, whereas "needs-triage" signals that triaging hasn't yet occurred.
  • The following labels "committed", "in-progress", "needs-review", and "done" feel a bit redundant to ZH/GH's baked-in capabilities. Unless we can automate these labels, I'm inclined to lean on the innate ZH/GH capabilities to reduce overhead.

What do you think? I'd be happy to chat about this over slack/zoom if that's easier/faster.

[pivotaljohn]

@pivotaljohn Love these thoughts! You bring up a lot of great points and suggestions. To build off of your suggestions, I have some thoughts:

• As general guidance, I view these labels to serve the team of maintainers as the primary target persona. I'm hoping that we can establish a minimum set of labels in order to streamline our ability to prioritize and schedule work to be done.

Agreed. "Apologies for the length of this letter, I didn't have time to write a shorter one."

• priority

  • priority/valuable-whenever. To me, "valuable-whenever" feels a bit too vague and may be difficult to relatively compare it to the other options (such as "important-longterm"). I still prefer something that states that the maintainers are not planning to schedule this work soon. "unprioritized-backlog" captures that well enough for me. "valuable-but-unprioritized" feels a bit wordy and with this set of labels, I don't think that anything "not valuable" will persist in our list of issues.

👍🏻 I had interpreted the tuples of "priority" as "level_of_importance-urgency_as_a_timeframe" maybe worth a few more minutes (zoom) to hash out options.

• If we strive to set priority and kind labels for every issue, I think we need a "priority/awaiting-more-evidence" option to show that this is not yet a priority because we need more information (i.e. from the requester or considering product fit). However, we could maybe just use the "blocked" labels to signify why a priority is not yet assigned.

Yeah... I'm starting to see what the stylistic difference here is: a process-orientation vs. an attribute-orientation.

• I like the reduced set of kind options.
• I'm wondering if we can do away with the component labels? I'm not sure if this adds much value and I'd like to minimize overhead.

yup... "components" arose in my head as a way to re-locate "documentation" somewhere.

• state

  • I prefer "needs-triage" to "in-triage". "in-triage" feels like an active state to me, whereas "needs-triage" signals that triaging hasn't yet occurred.
  • The following labels "committed", "in-progress", "needs-review", and "done" feel a bit redundant to ZH/GH's baked-in capabilities. Unless we can automate these labels, I'm inclined to lean on the innate ZH/GH capabilities to reduce overhead.

mmmmm.... that's interesting because I had assumed that these labels were an attempt to bridge between ZH and GH...

What do you think? I'd be happy to chat about this over slack/zoom if that's easier/faster.

Yeah, I think we can reconcile a bunch of stuff faster, synchronously.

[aaronshurley]

I had a chat with @jtigger and we came to to the following conclusion for now:

• prioritization
  • These feel like a pretty good collection already. We're going to leave these as they are today. We may want to update these when we think more about how we want to handle state.
• kind
  • We would like to update these to simplify our label set by using:
    • kind/enhancement # includes dependabot bumps
    • kind/bug
    • kind/support
    • kind/ops # eng-focused/non-feature work
• state
  • We're going to hold off on making any changes here for now. We'd like to explore what sort of automation we could introduce into our triaging/backlog mgmt process (such as GitHub Projects beta or further ZH possibilities).

Since it's Friday and I'm about to be OOO for 1.5 weeks, I'm not going to submit a PR today. I'll revisit this once I get back.

Please let us know if you have any thoughts on any of this.

[aaronshurley]

Just to provide a small update on this, it was mentioned that kind/ops can create some confusion considering the domain that we're in. kind/cleanup was suggested instead (this aligns with kubernetes labels).

[aaronshurley]

Planning to start this initiative after the contributor model lands (https://github.com/vmware-tanzu/carvel/issues/495)