Openj9: PROPOSAL: Labeling schema for managing issues

[aprenaud]

As this project grows, and the number of open issues being tracked grows, a common labeling schema will be helpful to manage the project's issues.

Taking some of the best practices at other large open projects I propose the following

• defining an small initial set of reserved labels generally applicable to majority of issues
• defining a reserved label colour for each category of label, ie. Priority labels are Green, component labels are blue. This enables quick location of relevant labels.
• label text should start with the category, ie. not "Medium", but "Pri: Medium", or "Comp: VM" . Helps new people identify purpose quickly
• Reserve a red "HOT" or similar red label for drawing attention to Urgent issues.

For the initial set of labels to define ( beyond the Git Default set)

• Priority,
• Component,
• Type (bug vs. discussion vs enhancement vs question),
• Size (fixed unitless values),
• JDK Level (as a project that supports multiple JDK API levels, identifying when a issue is unique to only 1 level will be useful),
• red "Hot" label,
• Beginner label to identify easy to take on work for new contributors.

Beyond that initial set, individuals might create their own labels as they find them useful, but conflicting with the project's defined set/colours should be discouraged.

[mgaudet]

:+1: (just a note, only committers can create or apply labels so the last para probably isn't necessary)

[DanHeidinga]

Other all I like this approach. Thanks for proposing this @aprenaud!

A couple of clarifying questions:

Priority,

High, Medium, Low? Or something more?

Type (bug vs. discussion vs enhancement vs question),

These are in the default set of labels.

JDK Level

jdk8, jdk9, jdk18.3, jdk18.9, etc?

Size

What do you suggest for this? I'm struggling to come up with an easy to apply set of size labels.

FYI @pshipton @mstoodle @jonathanw

[aprenaud]

I'll let you know what i was thinking, but certainly would like to hear other opinions.

Priority : assuming the project goes with a big red super urgent flag, then High, medium and Low would suffice for priority values. I've seldom seen value in tracking at any further resolution.

Type : I know the project has those but they are different colours currently . If you make them of the same colour at least then its very quick to spot if a "type" flag is missing, or if there are multiple "type" flags, so I would suggest at least that alteration to the defaults.

JDK : yes, that was idea, creating them as they are needed. Lack of JDK label implies general applicability.

Size : recommended the story point approach of an expanding integer series where relative size is the important factor. Using the Fibonacci sequence is popular.

[mstoodle]

+1 for me, but I think Size as proposed is going to be hard to calibrate. I would prefer we keep things simple (the proposal already has quite a few dimensions) and then we can expand the set of labels if we find it too hard to understand the set of things we have. I would leave "size" out of the initial set, personally.

We can assign colours ourselves, though someone with a better colour sense than I should do that assignment to avoid (me) creating an eye sore for everyone :) .

[gireeshpunathil]

+1 for the overall approach.

Color coding: Grouping different labels with same color and overloading a label with key and value can be confusing. Why can't we use unique color which in itself highlights the work item's attributes?

Priority: Classifying work items as high priority may cause an ambigeous effect on the rest of the items. Why can't we define labels that actually represent the reason for priority itself - such as release blocker, regression, production down etc.?

Also I want to introduce 2 more labels:

platform (platform specific items)
status (applicable only for PRs - to denote their progress status.) Without this, people tend to overload the subject line which is kind of ugly.

[aprenaud]

key and value: I'm not sure how additional information can be confusing as long as its consistent. Without the key information, new developers would have to refer to a document in some cases to decipher label purpose. However, I don't know that's a problem per se so I'm not going argue strongly for it. I can appreciate the aesthetics of removing the key and just listing the value.

Priority - Here I will have to disagree. High/med/Low is pretty unambiguous compared to even the three suggestions you made. Simply listing the impact leaves it to the value judgement of the reader as to which of those is higher priority, which may not correspond to the project's view. Even the project itself might consider the relative priority of those items differently at different times in its development cycle and using the impact, which wouldn't change, as a label doesn't allow project leads to communicate that change in priority via simple to interpret labels.

Platforms: I could see the utility of this.
Status: Right now there are three states : open and unassigned, open and assigned, closed. Which additional states for pull requests do you feel are necessary for the project to track?

[mgaudet]

While I am not personally decided as to whether we should deploy this for OpenJ9, there are some extra states that can be useful: _Ready For Review_, _Ready to Merge_, _Pending Dependency_.

[gireeshpunathil]

@aprenaud - thanks, I see your point on priority.

Which additional states for pull requests do you feel are necessary for the project to track?

• WIP (work in progress, not-ready-for-review). Currently this is applied on the PR title itself, and removed when ready for review
• Paused (due to un-anticipated dependency that occurred in the middle of progress)
• Backport pending (if we wish to mark it here)

[DanHeidinga]

"Keep it simple" should be a guiding principle for label design. I'm operating under the assumption we can always add more labels later if they become necessary so I'd like to keep the initial set as small as possibleI.

@gireeshpunathil Using "WIP" in the PR title is a well known technique for marking work in progress so I'd prefer to stick with what users already know. Contributors can't add labels yet they need a way to indicate WIP / paused states. Sticking with the modifying the title for this is sufficient to cover both.

A "backport pending" label is good idea. It should be created when it's first needed, likely when OpenJ9 has LTS branches.

Based on discussion so far, I'm hearing consensus for the following labels. I've added a colour scheme as a strawman that hopefully isn't too hard on the eyes.

Priority (green #0e8a16)
pri:high, pri:medium, pri:low

JDK:(orange #d93f0b)
jdk8, jdk9, jdk18.3

Component: (blue #1d76db)
comp:vm, comp:jit, comp:test, comp:doc.

And two extra labels:
hot (red)
beginner (yellow #fbca04)

[charliegracie]

I would propose comp:gc as another component label but other than that it seems like a great start @DanHeidinga

[DanHeidinga]

Thanks @charliegracie. I knew I missing something important... =)

[gireeshpunathil]

how about the type from @aprenaud 's list? I guess that is important too - we need to classify the content based on the nature (discussion vs. question etc.) as well as impact (breaking changes, changing default, doc update needed etc. for PRs)

[DanHeidinga]

@gireeshpunathil The proposed types are covered by github's default set of labels.

[gireeshpunathil]

@DanHeidinga - ok thanks, so that completes the list I guess.

[DanHeidinga]

Labels have been created. Closing this.

[mleipe]

+1

[charliegracie]

I would like to propose that we add one more component or a new type complete. I would suggest that we add a comp:omr or a dependent:omr tag so that it is obvious that a change is a dependent on changes in the OMR repo.

An example would be a label for PR #211

[mgaudet]

I'd lean to dependent:omr

[aprenaud]

+1

[DanHeidinga]

@charliegracie great idea! We'll likely need one for the extensions project as well.

depends:omr
depends:openjdk9

And add other openjdkX dependency labels as required.

[DanHeidinga]

I've created the two labels described in the previous comment so we can start using them right away. They can always be modified (or removed) if there is further conversation on the right naming, other depends:, etc

[DanHeidinga]

I've created two additional labels to track work related to OpenJDK projects: project:panama & project:valhalla

[DanHeidinga]

Closing this again - it can be reopened when / if new labels are being proposed

[andrewcraik]

I'd like to propose a perf or performance label for issues that are related to performance so we can filter them from the items related to new language features or functional issues. Thoughts?

[andrewcraik]

@DanHeidinga @mstoodle @0xdaryl ^^?

[DanHeidinga]

@andrewcraik Can you suggest some guidance on what issues / PRs would get a performance tag?

I'm fine with creating a label for it. I'll note that we're not consistently applying the labeling scheme we've created so far and new labels are likely to get the same semi-consistent application.

[andrewcraik]

To start with #375 and #389 - I expect there to be more as more people look at OpenJ9 and as the focus shifts more towards Java 9 and Java 18.3 and later - support for new APIs, new idioms and general perf improvement work.

[mstoodle]

It could also be used to tag performance “bugs”.

+1

[0xdaryl]

+1 for a perf label.

If you really want to over-engineer this you could make 'perf' the general category and provide subcategories for the kind of performance like some of the other labels do:

perf:throughput
perf:footprint
perf:startup
perf:compile

[DanHeidinga]

I see a perf label has been created. Closing this again.

[aprenaud]

@0xdaryl the use of the colon in labels thus far are as Category:qualifier, not category:subcategory. The category applies to everything, but the category itself has no distinct meaning, ie. Pri:, or depends: by themselves say nothing. The part after the colon are the qualifiers, which add meaning. i.e. Pri: High. To use perf in the way you suggest would break that usage model. Not saying you couldn't do it, but be aware you would be creating a different usage model - the inconsistency might create confusion.