Labelling issues

Why labelling

Labels are important to communicate to others what the issue is about. You may think that the description is sufficient, but would you want to have read all descriptions to be able to quickly determine what issues are about the client, the controller, the segment store, etc.? Of course not, it is much more convenient and efficient to simply filter according to a label.

The labels are also critical from a project management perspective. We need them to understand how many bugs are being reported, how many being resolved, which component is generating more issues, etc. We can produce all these indicators by using labels.

This page describes the scheme we are using and it is meant to serve as a guide that contributors should follow to label issues correctly.

Two-level hierarchy

We currently use a hierarchy of two levels and the idea is that, for an issue, we select at least one option from each first-level category. The categories are:

• Area
• Kind
• Priority
• Status
• Version

Let's elaborate on each one of these categories.

Functional area

The area is the component or aspect of the project that the issue is about. For example, if the issue is about the client, then the label area/client is appropriate. If it is about the controller, then area/controller. In some cases, multiple labels apply. For example, if the issue is reporting a bug in the controller, then both area/controller and area/testing apply. Mark all area labels that apply.

Kind of issue

An issue might be reporting a bug or describing a new feature, and we need to label it accordingly. For this category, there should be really a single choice.

The current options are:

Kind	Description
kind/bug	Bugs are bugs. The cause may or may not be known at triage time so debugging should be accounted for in the time estimate.
kind/enhancement	Enhancements are not bugs or new features but can improve the usability or performance of a project component.
kind/feature	Functionality or other elements that the project does not currently support. Features are new and shiny.
kind/question	Contains a user or contributor question requiring a response.
kind/PDP	An issue to discuss a design proposal. It must be accompanied by a PDP wiki page.
kind/notanissue	We have decided that this is not an issue we can or want to address.

Priority

We current have four options: p0-p3, being p0 the highest and p3 the lowest. The priority has two interpretations:

• Order of execution: A higher priority task should be executed before another
• Bug severity: The priority of a bug issue indicates how severe the problem is.

We are going to use the following definitions for severity:

• priority/p0: Data loss/corruption, catastrophic failure, security, functionality lost, permanent damage
• priority/p1: Recoverable error or application crash, functionality/performance impaired but not lost, no permanent damage
• priority/p2: Slight inconvenience or annoyance to applications, system continues to function
• priority/p3: No direct impact to applications, e.g., typos in documentation or log messages

Status

The status is supposed to reflect the workflow of the issue so that an external collaborator can tell the state of the current issue. The current options are the following:

Status	Description
no status	Issue has been created, not yet validated by reproducing the claimed bug or not yet accepted due to lack of justification.
status/accepted	Apply to enhancements / feature requests that we think are good to have. Adding this label helps contributors find things to work on. Serves as a backlog.
status/rejected	Apply to enhancements / requests that have been discussed and found to be unnecessary, or not aligned with Pravega roadmap. Once rejected, issue needs to be closed asap.
status/more-info-needed	Apply this to issues that are missing information (eventually we need to update Issue Template that requires Pravega Version, Runtime environment ..), or require feedback from the reporter. If the issue is not updated after a week, it can generally be closed.
status/in-progress	Apply this label if an issue has been picked up by a developer and is in design discussion/development
status/needs-attention	Apply this label if an issue (or PR) needs more eyes.

A user can create an issue to request a feature or report a bug. Once such an issue is analyzed by a developer, we can change the status to:

• accepted in the case the developer believes we can and should do it.
• in-progress in the case the developer has started working on it.
• needs-attention in the case the developer is not sure and needs someone else to look at it.

Often developers create their own issues, and in such cases, we can directly mark the issues accepted or in-progress depending on whether it is going to be worked upon later or immediately, respectively.

Version

By default, an issue is to be addressed in the next upcoming feature release, unless it is a bug that affects release branches and we need a bug-fix release for that release branch.

If an issue has multiple versions, it means that it needs to be addressed across release branches. Do not close an issue in the case it is not addressed in all marked versions.

Tags

There is an additional category for special cases. At the moment, we only have tag/breaksAPI to indicate that a particular PR breaks compatibility.

The tag/breaksAPI label is to be used with both issues and pull requests. All other labels are for issues only.