GitHub issue labels

github

(Matt McCormick) #1

Hi folks,

For our transition to GitHub for issue tracking:

are there preferences for issue label names? Some proposed so far are Enhancement, Warning, CMake


(Dženan Zukić) #2

We could just plagiarize commit message prefixes:

  • BUG: Fix for runtime crash or incorrect result
  • COMP: Compiler error or warning fix
  • DOC: Documentation change
  • ENH: New functionality
  • PERF: Performance improvement
  • STYLE: No logic impact (indentation, comments)
  • WIP: Work In Progress not ready for merge

All of these except for WIP can be turned into labels: Bug, Compilation, Documentation, Enhancement, Performance, Style. We could introduce additional labels, e.g. CMake or Build.


(Pablo Hernandez-Cerdan) #3

Also for the WIP case, we can have this robot: https://github.com/apps/wip

I have never used it, but this avoids merging WIPs…


(Matt McCormick) #4

Good idea! We could also add a bot to automatically add the labels based on the prefix. Issue created to track this here:

Sweet! The wip app has been installed on the InsightSoftwareConsortium GitHub Organization and applied to all member repositories.


(Jon Haitz Legarreta Gorroño) #5

:thumbsup:

Preventing WIP’s to be merged is a nice and can avoid issues, while maintaining a clean history, I think.

The VTK folks have large number of labels:
https://gitlab.kitware.com/vtk/vtk/labels

They make a nice use of them, but I acknowledge that being specific with some issues is hard. I do not have a clear saying about whether we should split ours (e.g. area:filtering or area:segmentation, etc.).

Or whether adding additional labels such as priority based, or status (e.g. status:blocked, status:awaiting data, etc.) is an unnecessary level of detail.

I think the template has also room for improvement. Comments are welcome.


(Bradley Lowekamp) #6

Related to the labels is the workflow used to manage the project’s issues which includes the phases of an issue along with assignment, categorization and scheduling. JIRA was very loaded with these types of features that we did not use. The issues in Github are sometimes feature requests, bug reports or just a user needed help with a question.

The labels I have in SimpleITK are: Assigned, Backlog, Blocker, Bug Report, Confirmed Bug, Duplicate, Feature Request, Feedback, Help Wanted, Invalid ( I don’t think I’ve used this one), Help Wanted, Question, Pending Update ( backed by something else).

This has labels for the type of issue: Feature Request, Questions, Bug Report->Confirmed Bug
Assignment: Assigned ( some one should be working on it ), Help Wanted ( no one is working on it), Feedback ( waiting on reporter )
There are no categories with these label. With a larger project categorization of issues can be used to get the attention of people who are experiences in that area of the project.

A lot of it come down to how we use the issue is Github, then creating labels to enable and enhance that process.


(Jon Haitz Legarreta Gorroño) #7

The SimpleITK categorization resembles in some ways the one in VTK.

So my vote goes to this type of graining and labelling according to the phase/workflow of the issue beyond the type the of the issue.


(Jon Haitz Legarreta Gorroño) #8

So what is the consensus?

Also, would the bot you mention @matt.mccormick able to produce custom labels, or just based on the commit message subject title?


(Matt McCormick) #9

I agree that the other categories of labels, like language, etc. could be useful and we should inspire from VTK and SimpleITK.

That said, we should be careful to only create labels that will be actually used, and that do not incur more burden or distraction than their usefulness. We also do not want an overwhelming number of labels.

I think we should add new labels on an as-needed basis.

We could add whatever custom logic we want to the bot. This could help reduce the burden of manually adding and removing labels.

What do you think?


(Jon Haitz Legarreta Gorroño) #10

I do agree that we should not add more labels than those that will be actually used and avoid an overwhelming number of them. So there is a trade-off between the grain and the use.

Here is a first proposal from which we could draw a shortlist:

  • “Type: Bug” (Inconsistencies or issues which will cause an issue or incorrect result under some or all circumstances)
  • “Type: Compiler” (Compiler support or related warnings)
  • “Type: Maintenance” (Infrastructure/ecosystem related changes, such as CMake or buildbots)
  • “Type: Performance” (Improvement in terms of compilation or execution time)
  • “Type: Enhancement” (Improvement of existing methods or implementation)
  • “Type: Feature request” (Request for new functionality or feature)

  • “Priority: Critical” (Should be addressed ASAP. Not fixing this issue is linked with inconsistencies or errors)
  • “Priority: High” (After critical issues are fixed, these should be fixed with before any further issues)
  • “Priority: Medium” (This issue may be useful, and needs some attention)
  • “Priority: Low” (Results are not affected if this is not implemented, but addressing it will improve the usefulness of a class or method)

  • “Status: Backlog” (Postponed without a fixed deadline)
  • “Status: Blocked” (Blocked by some other issue which needs to be resolved first or by some other cause)
  • “Status: Confirmed” (Confirmed/reproduced issue on a different machine with same or similar settings to those reported)
  • “Status: Need info” (Further clarification or new data required)

  • “Area: Bridge
  • “Area: Core
  • “Area: Filtering
  • “Area: IO
  • “Area: Registration
  • “Area: Segmentation
  • “Area: ThirdParty
  • “Area: Video
  • “Area: Testing” (Ensure that the purpose of a class is met/the results on a set of test cases as wide as possible are correct)
  • “Area: Documentation” (Documentation improvement or change)
  • “Area: Examples” (Demonstration of the use of classes)
  • “Area: Python wrap” (Python bindings for a class)

  • “Triage: Easy

If too elaborated/long, feel free to modify it better match our needs.

Comments are welcome.


(Matt McCormick) #11

Good proposal, @jhlegarreta. Some thoughts inline:

Nice.

I think Maintenance could be re-named to Infrastructure, since it is more specific.

Feature request could be removed, since there is a lot of overlap with other types and it does not correspond to existing commit prefixes.

We may want to add Style to cover existing pre-commit prefix topics.

I do not think we should use these. They are subjective – the person submitting the issue almost always thinks it is critical. And it does not add a lot of value relative to burden to create it and their clutter.

:+1:

a grammar tweak: Need info -> Needs info.

There are a lot of these, but we could possibly automate them for pull requests with a bot.

Python wrap -> Python wrapping is preferred grammar.

Easy is relative and could diminish the effort a new contributor makes.

We should have some label that marks an issue as a good starting point for a new contributor. Good first issue seems to be common in GitHub and descriptive.


@phcerdan tried adding Closes #XXX in his Git commit message that was pushed via Gerrit, and GitHub automatically closed the issue. Hurrah! :sunny:


(Jon Haitz Legarreta Gorroño) #12

Thanks for the comments Matt. I see your points.

That’d awesome for PR’s. Ideally our issues would come first (and would need to be labelled manually), and the issue would be cross referenced in the PR message.

Absolutely brilliant guys :sparkler:.

So if no other comments exist about the list, I’d go ahead and create the labels, and then we’ll figure out about the bot to add them automatically to PRs.

I’ll relabel the existing issues if their current labels do not correspond to our final list.


(Matt McCormick) #13

In GitHub, each pull request is referenced like a issue. A pull request has the same labels and discussion features of an issue. To keep discussion in one place, avoid ceremonial busywork, enable automatic labels, and keep productivity high, we should strive to only create a separate issue when a pull request is not yet ready.

Great, thanks. :clap:


(Jon Haitz Legarreta Gorroño) #14

Folks,
the ITK repository labels have been created:


(Hans Johnson) #15

We need to have a concise description of the intended use of labels. (summarize this blog in the comtributing guide or README file)

< ! - - Labels have 3 categories that can be assigned “area: (blue hued label), type (yellow hued label):, status: (purple hued label)”, Please consider picking one label from each of these categories in order to add easily searchable informtion to the issue. -->

My critique of how the labeling system could be improved:

critique: I think the “type:Bug” issue is too ambiguous in that is really overlaps with all other types. in some respects all the other type: issues are all bugs.

critique: A new label category would complete the statndard sorting of importantce for “ugency:[0Critial | 1High | 2Medium | 3Low | 4Unnecessary]”. Color from bright red to white in decending color scheme.

critique: All labels need a description.

critique: status labels should have a progression “status: [0Active | 0Blocked | 2Confirmed | 3NeedsInfo | 4Backlog]” in gradient of dark purple to light purple.