Come up with an issue labeling scheme

[jasonkuhrt]

Original effort can be found in this PR on prisma/prisma-label-sync.

Revised 1.0.0 Sketch

NOTE: This is a live sketch that will be updated inline over course of discussion

• Choosing type over kind and scope over area to align with conventional commits terminology.
• ... denotes extensible at individual repo level
• Tempted to use effort/1-hours effort/2-days effort/3-weeks instead of complexity. But complexity gives a bit more latitude and aligns with well trodden scrum term/concept... Also maybe we need both concepts anyways e.g. docs are low complexity but may take days...
• Tempted to use impact/few-users impact/some-users impact/many-users instead of low-high. The former is clearer but the later gives more latitude, e.g. internal architectural changes that provide for long term strategic openings. Also the former overlaps with the freq concept found in Angular which would imply also being open to the same criticism found there (my comment): but seems like emoji issue reactions serve that purpose

type/
feature bug chore perf docs tests refactor question support meta

status/
thinking ready blocked

scope/
error-handling cicd ...

note/
duplicate invalid wontfix breaking-change ...

needs/
clarification investigation use-cases

community/
good-first-issue help-wanted

impact/
high medium low

easy modest hard

Research

React https://github.com/facebook/react/labels

• Calls scope component
• Has group “resolution” containing duplicate invalid
• Has variants good first issue [(taken)]
• “breaking change” label

Kubernetes https://github.com/kubernetes/kubernetes/issues/labels

• Calls scope area
• Calls type kind
• Has group “lifecycle” containing rotten stale …
• Has group “needs”
• Has group “size” S-XXL based on LOC diff
• Has group “triage” containing “needs-information” “support” “duplicate” …
• Has ¯_(ツ)_/¯ label

Angular https://github.com/angular/angular/labels

• Calls scope "comp" (so, "component" idiom here)
• Has group "docsarea"
• Has group "effort" formed like so "effort#: [hours|days|weeks]"
• Has group "flag" containing "breaking change" ...
• Has group "freq" formed like so "freq#: [low|medium|high|critical]"
• Has group "workaround" formd like so: "workaround#: obvious|non-obvious|complex|none"
• Calls status state

Comments

• Labels like "¯_(ツ)_/¯" are charming but unusable for search filtering with gh ui IIUC
• "freq" flag is interesting but seems like emoji issue reactions serve that purpose
• We could adopt Angular effort label in place of complexity
• triage label group is interesting
• maybe rename "scope" to "area" as per kubernetes and aligning with existing prisma--but this deviates from conventional commit terminology...

[jasonkuhrt]

Research

Terraform https://github.com/hashicorp/terraform/labels

• Calls "exploring"/"discussing" "thinking"

Comments

• Going to try replacing exploring with thinking

[janpio]

• maybe rename "scope" to "area" as per kubernetes and aligning with existing prisma--but this deviates from conventional commit terminology...

@prisma is not totally sure if they will keep using these - Switching to type and scope (or in general conventional commits conventions) might be in our future (depending on repo though, I think scope and area even are different things.) - so don't let you influence too much by that.

[jasonkuhrt]

@janpio thanks for the input! Curious, for you, how would you define scope and area. The definition of scope in in conventional commit is:

A scope MUST consist of a noun describing a section of the codebase

I think terms I've spec'd above like error-handling cicd stretch this. They are not clearly parts of the codebase, but more like themes. Maybe in fact this is better suited to the term area.

[janpio]

Curious, for you, how would you define scope and area.

In my mind scope is connected to the code structure, and area is more a conceptual thing - or theme as you call it. For a repo like prisma/specs where code is not really a thing (but content), and we are more talking/writing about ideas and concepts, area feels better than the scope (that has this more concrete definition from conventional commits et al).

A scope MUST consist of a noun describing a section of the codebase

I think terms I've spec'd above like error-handling cicd stretch this. They are not clearly parts of the codebase, but more like themes.

Rules (like "MUST") are there to be broken, right? 🤷‍♀

I personally have a printout of the Angular (?) version of the available types next to my monitor: build, ci, docs, feat, fix, perf, refactor, style, test (and manually scribbled: chore). This tends to work for my personal projects.

Using that, you could get rid of the cicd scope by using the ci type. error-handling though I would just keep and ignore "section of the codebase" and replace with "something in the codebase" - tadaa the modified is still satisfied.

Mixing area and scope seems like unnecessary complexity in the mental model. It's hard enough to figure out which one of the types to use sometimes - and the benefit of getting it super right is pretty small.

[jasonkuhrt]

@Weakky and I independently came to the same feeling that we can simplify the complexity labels into just easy modest and hard. Less granularity, yes. Let's try this simplified form.

While they won't be namespaced we can use coloring to help group them.

- complexity/
- 1-skateboard 2-bicycle 3-motorcycle 5-truck 8-hovercraft 13-spaceship

[jasonkuhrt]

Considering closed now via https://github.com/prisma-labs/prisma-labs-labelsync