347 lines
16 KiB
Markdown
347 lines
16 KiB
Markdown
---
|
|
stage: none
|
|
group: Development
|
|
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
|
|
---
|
|
|
|
# Labels
|
|
|
|
To allow for asynchronous issue handling, we use [milestones](https://gitlab.com/groups/gitlab-org/-/milestones)
|
|
and [labels](https://gitlab.com/gitlab-org/gitlab/-/labels). Leads and product managers handle most of the
|
|
scheduling into milestones. Labeling is a task for everyone. (For some projects, labels can be set only by GitLab team members and not by community contributors).
|
|
|
|
Most issues will have labels for at least one of the following:
|
|
|
|
- Type. For example: `~"type::feature"`, `~"type::bug"`, or `~"type::maintenance"`.
|
|
- Stage. For example: `~"devops::plan"` or `~"devops::create"`.
|
|
- Group. For example: `~"group::source code"`, `~"group::knowledge"`, or `~"group::editor"`.
|
|
- Category. For example: `~"Category:Code Analytics"`, `~"Category:DevOps Reports"`, or `~"Category:Templates"`.
|
|
- Feature. For example: `~wiki`, `~ldap`, `~api`, `~issues`, or `~"merge requests"`.
|
|
- Department: `~UX`, `~Quality`
|
|
- Team: `~"Technical Writing"`, `~Delivery`
|
|
- Specialization: `~frontend`, `~backend`, `~documentation`
|
|
- Release Scoping: `~Deliverable`, `~Stretch`, `~"Next Patch Release"`
|
|
- Priority: `~"priority::1"`, `~"priority::2"`, `~"priority::3"`, `~"priority::4"`
|
|
- Severity: `~"severity::1"`, `~"severity::2"`, `~"severity::3"`, `~"severity::4"`
|
|
|
|
Please add `~"breaking change"` label if the issue can be considered as a [breaking change](../deprecation_guidelines/index.md).
|
|
|
|
Please add `~security` label if the issue is related to application security.
|
|
|
|
All labels, their meaning and priority are defined on the
|
|
[labels page](https://gitlab.com/gitlab-org/gitlab/-/labels).
|
|
|
|
If you come across an issue that has none of these, and you're allowed to set
|
|
labels, you can _always_ add the type, stage, group, and often the category/feature labels.
|
|
|
|
## Type labels
|
|
|
|
Type labels are very important. They define what kind of issue this is. Every
|
|
issue should have one and only one.
|
|
|
|
The SSOT for type and subtype labels is [available in the handbook](https://about.gitlab.com/handbook/engineering/metrics/#work-type-classification).
|
|
|
|
A number of type labels have a priority assigned to them, which automatically
|
|
makes them float to the top, depending on their importance.
|
|
|
|
Type labels are always lowercase, and can have any color, besides blue (which is
|
|
already reserved for category labels).
|
|
|
|
The descriptions on the [labels page](https://gitlab.com/groups/gitlab-org/-/labels)
|
|
explain what falls under each type label.
|
|
|
|
The GitLab handbook documents [when something is a bug](https://about.gitlab.com/handbook/product/product-processes/#bug-issues) and [when it is a feature request](https://about.gitlab.com/handbook/product/product-processes/#feature-issues).
|
|
|
|
## Stage labels
|
|
|
|
Stage labels specify which [stage](https://about.gitlab.com/handbook/product/categories/#hierarchy) the issue belongs to.
|
|
|
|
### Naming and color convention
|
|
|
|
Stage labels respects the `devops::<stage_key>` naming convention.
|
|
`<stage_key>` is the stage key as it is in the single source of truth for stages at
|
|
<https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml>
|
|
with `_` replaced with a space.
|
|
|
|
For instance, the "Manage" stage is represented by the `~"devops::manage"` label in
|
|
the `gitlab-org` group since its key under `stages` is `manage`.
|
|
|
|
The current stage labels can be found by [searching the labels list for `devops::`](https://gitlab.com/groups/gitlab-org/-/labels?search=devops::).
|
|
|
|
These labels are [scoped labels](../../user/project/labels.md#scoped-labels)
|
|
and thus are mutually exclusive.
|
|
|
|
The Stage labels are used to generate the [direction pages](https://about.gitlab.com/direction/) automatically.
|
|
|
|
## Group labels
|
|
|
|
Group labels specify which [groups](https://about.gitlab.com/company/team/structure/#product-groups) the issue belongs to.
|
|
|
|
It's highly recommended to add a group label, as it's used by our triage
|
|
automation to
|
|
[infer the correct stage label](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-labelling-of-issues-and-merge-requests).
|
|
|
|
### Naming and color convention
|
|
|
|
Group labels respects the `group::<group_key>` naming convention and
|
|
their color is `#A8D695`.
|
|
`<group_key>` is the group key as it is in the single source of truth for groups at
|
|
<https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml>,
|
|
with `_` replaced with a space.
|
|
|
|
For instance, the "Pipeline Execution" group is represented by the
|
|
`~"group::pipeline execution"` label in the `gitlab-org` group since its key
|
|
under `stages.manage.groups` is `pipeline_execution`.
|
|
|
|
The current group labels can be found by [searching the labels list for `group::`](https://gitlab.com/groups/gitlab-org/-/labels?search=group::).
|
|
|
|
These labels are [scoped labels](../../user/project/labels.md#scoped-labels)
|
|
and thus are mutually exclusive.
|
|
|
|
You can find the groups listed in the [Product Stages, Groups, and Categories](https://about.gitlab.com/handbook/product/categories/) page.
|
|
|
|
We use the term group to map down product requirements from our product stages.
|
|
As a team needs some way to collect the work their members are planning to be assigned to, we use the `~group::` labels to do so.
|
|
|
|
## Category labels
|
|
|
|
From the handbook's
|
|
[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/categories/#hierarchy)
|
|
page:
|
|
|
|
> Categories are high-level capabilities that may be a standalone product at
|
|
another company, such as Portfolio Management, for example.
|
|
|
|
It's highly recommended to add a category label, as it's used by our triage
|
|
automation to
|
|
[infer the correct group and stage labels](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-labelling-of-issues).
|
|
|
|
If you are an expert in a particular area, it makes it easier to find issues to
|
|
work on. You can also subscribe to those labels to receive an email each time an
|
|
issue is labeled with a category label corresponding to your expertise.
|
|
|
|
### Naming and color convention
|
|
|
|
Category labels respects the `Category:<Category Name>` naming convention and
|
|
their color is `#428BCA`.
|
|
`<Category Name>` is the category name as it is in the single source of truth for categories at
|
|
<https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml>.
|
|
|
|
For instance, the "DevOps Reports" category is represented by the
|
|
`~"Category:DevOps Reports"` label in the `gitlab-org` group since its
|
|
`devops_reports.name` value is "DevOps Reports".
|
|
|
|
If a category's label doesn't respect this naming convention, it should be specified
|
|
with [the `label` attribute](https://about.gitlab.com/handbook/marketing/digital-experience/website/#category-attributes)
|
|
in <https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml>.
|
|
|
|
## Feature labels
|
|
|
|
From the handbook's
|
|
[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/categories/#hierarchy)
|
|
page:
|
|
|
|
> Features: Small, discrete functionalities, for example Issue weights. Some common
|
|
features are listed within parentheses to facilitate finding responsible PMs by keyword.
|
|
|
|
It's highly recommended to add a feature label if no category label applies, as
|
|
it's used by our triage automation to
|
|
[infer the correct group and stage labels](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-labelling-of-issues).
|
|
|
|
If you are an expert in a particular area, it makes it easier to find issues to
|
|
work on. You can also subscribe to those labels to receive an email each time an
|
|
issue is labeled with a feature label corresponding to your expertise.
|
|
|
|
Examples of feature labels are `~wiki`, `~ldap`, `~api`, `~issues`, and `~"merge requests"`.
|
|
|
|
### Naming and color convention
|
|
|
|
Feature labels are all-lowercase.
|
|
|
|
## Workflow labels
|
|
|
|
Issues use the following workflow labels to specify the current issue status:
|
|
|
|
- `~"workflow::awaiting security release"`
|
|
- `~"workflow::blocked"`
|
|
- `~"workflow::complete"`
|
|
- `~"workflow::design"`
|
|
- `~"workflow::feature-flagged"`
|
|
- `~"workflow::in dev"`
|
|
- `~"workflow::in review"`
|
|
- `~"workflow::planning breakdown"`
|
|
- `~"workflow::problem validation"`
|
|
- `~"workflow::production"`
|
|
- `~"workflow::ready for design"`
|
|
- `~"workflow::ready for development"`
|
|
- `~"workflow::refinement"`
|
|
- `~"workflow::scheduling"`
|
|
- `~"workflow::solution validation"`
|
|
- `~"workflow::start"`
|
|
- `~"workflow::validation backlog"`
|
|
- `~"workflow::verification"`
|
|
|
|
## Facet labels
|
|
|
|
To track additional information or context about created issues, developers may
|
|
add _facet labels_. Facet labels are also sometimes used for issue prioritization
|
|
or for measurements (such as time to close). An example of a facet label is the
|
|
`~"customer"` label, which indicates customer interest.
|
|
|
|
## Department labels
|
|
|
|
The current department labels are:
|
|
|
|
- `~"UX"`
|
|
- `~"Quality"`
|
|
|
|
## Team labels
|
|
|
|
**Important**: Most of the historical team labels (like Manage or Plan) are
|
|
now deprecated in favor of [Group labels](#group-labels) and [Stage labels](#stage-labels).
|
|
|
|
Team labels specify what team is responsible for this issue.
|
|
Assigning a team label makes sure issues get the attention of the appropriate
|
|
people.
|
|
|
|
The current team labels are:
|
|
|
|
- `~"Delivery"~`
|
|
- `~"Technical Writing"`
|
|
|
|
### Naming and color convention
|
|
|
|
Team labels are always capitalized so that they show up as the first label for
|
|
any issue.
|
|
|
|
## Specialization labels
|
|
|
|
These labels narrow the [specialization](https://about.gitlab.com/company/team/structure/#specialist) on a unit of work.
|
|
|
|
- `~"frontend"`
|
|
- `~"backend"`
|
|
- `~"documentation"`
|
|
|
|
## Release scoping labels
|
|
|
|
Release Scoping labels help us clearly communicate expectations of the work for the
|
|
release. There are three levels of Release Scoping labels:
|
|
|
|
- `~"Deliverable"`: Issues that are expected to be delivered in the current
|
|
milestone.
|
|
- `~"Stretch"`: Issues that are a stretch goal for delivering in the current
|
|
milestone. If these issues are not done in the current release, they will
|
|
strongly be considered for the next release.
|
|
- `~"Next Patch Release"`: Issues to put in the next patch release. Work on these
|
|
first, and follow the [patch release runbook](https://gitlab.com/gitlab-org/release/docs/-/blob/master/general/patch/engineers.md) to backport the bug fix to the current version.
|
|
|
|
Each issue scheduled for the current milestone should be labeled `~"Deliverable"~`
|
|
or `~"Stretch"`. Any open issue for a previous milestone should be labeled
|
|
`~"Next Patch Release"`, or otherwise rescheduled to a different milestone.
|
|
|
|
## Priority labels
|
|
|
|
We have the following priority labels:
|
|
|
|
- `~"priority::1"`
|
|
- `~"priority::2"`
|
|
- `~"priority::3"`
|
|
- `~"priority::4"`
|
|
|
|
Please refer to the issue triage [priority label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#priority) section in our handbook to see how it's used.
|
|
|
|
## Severity labels
|
|
|
|
We have the following severity labels:
|
|
|
|
- `~"severity::1"`
|
|
- `~"severity::2"`
|
|
- `~"severity::3"`
|
|
- `~"severity::4"`
|
|
|
|
Please refer to the issue triage [severity label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#severity) section in our handbook to see how it's used.
|
|
|
|
## Label for community contributors
|
|
|
|
There are many issues that have a clear solution with uncontroversial benefit to GitLab users.
|
|
However, GitLab might not have the capacity for all these proposals in the current roadmap.
|
|
These issues are labeled `~"Seeking community contributions"` because we welcome merge requests to resolve them.
|
|
|
|
Community contributors can submit merge requests for any issue they want, but
|
|
the `~"Seeking community contributions"` label has a special meaning. It points to
|
|
changes that:
|
|
|
|
1. We already agreed on,
|
|
1. Are well-defined,
|
|
1. Are likely to get accepted by a maintainer.
|
|
|
|
We want to avoid a situation when a contributor picks an
|
|
~"Seeking community contributions" issue and then their merge request gets closed,
|
|
because we realize that it does not fit our vision, or we want to solve it in a
|
|
different way.
|
|
|
|
We manually add the `~"Seeking community contributions"` label to issues
|
|
that fit the criteria described above.
|
|
We do not automatically add this label, because it requires human evaluation.
|
|
|
|
We recommend people that have never contributed to any open source project to
|
|
look for issues labeled `~"Seeking community contributions"` with a
|
|
[weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?sort=created_date&state=opened&label_name[]=Seeking+community+contributions&assignee_id=None&weight=1) or the `~"quick win"`
|
|
[label](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&state=opened&label_name[]=quick%20win&assignee_id=None)
|
|
attached to it.
|
|
More experienced contributors are very welcome to tackle
|
|
[any of them](https://gitlab.com/groups/gitlab-org/-/issues?sort=created_date&state=opened&label_name[]=Seeking+community+contributions&assignee_id=None).
|
|
|
|
For more complex features that have a weight of 2 or more and clear scope, we recommend looking at issues
|
|
with the [label `~"Community Challenge"`](https://gitlab.com/gitlab-org/gitlab/-/issues?sort=created_date&state=opened&label_name[]=Seeking+community+contributions&label_name[]=Community+challenge).
|
|
If your MR for the `~"Community Challenge"` issue gets merged, you will also have a chance to win a custom
|
|
GitLab merchandise.
|
|
|
|
If you've decided that you would like to work on an issue, please @-mention
|
|
the [appropriate product manager](https://about.gitlab.com/handbook/product/#who-to-talk-to-for-what)
|
|
as soon as possible. The product manager will then pull in appropriate GitLab team
|
|
members to further discuss scope, design, and technical considerations. This will
|
|
ensure that your contribution is aligned with the GitLab product and minimize
|
|
any rework and delay in getting it merged into main.
|
|
|
|
GitLab team members who apply the `~"Seeking community contributions"` label to an issue
|
|
should update the issue description with a responsible product manager, inviting
|
|
any potential community contributor to @-mention per above.
|
|
|
|
## Stewardship label
|
|
|
|
For issues related to the open source stewardship of GitLab,
|
|
there is the `~"stewardship"` label.
|
|
|
|
This label is to be used for issues in which the stewardship of GitLab
|
|
is a topic of discussion. For instance if GitLab Inc. is planning to add
|
|
features from GitLab EE to GitLab CE, related issues would be labeled with
|
|
`~"stewardship"`.
|
|
|
|
A recent example of this was the issue for
|
|
[bringing the time tracking API to GitLab CE](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/25517#note_20019084).
|
|
|
|
## Technical and UX debt
|
|
|
|
In order to track things that can be improved in the GitLab codebase,
|
|
we use the `~"technical debt"` label in the [GitLab issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues).
|
|
We use the `~"UX debt"` label when we choose to deviate from the MVC, in a way that harms the user experience.
|
|
|
|
These labels should be added to issues that describe things that can be improved,
|
|
shortcuts that have been taken, features that need additional attention, and all
|
|
other things that have been left behind due to high velocity of development.
|
|
For example, code that needs refactoring should use the `~"technical debt"` label,
|
|
something that didn't ship according to our Design System guidelines should
|
|
use the `~"UX debt"` label.
|
|
|
|
Everyone can create an issue, though you may need to ask for adding a specific
|
|
label, if you do not have permissions to do it by yourself. Additional labels
|
|
can be combined with these labels, to make it easier to schedule
|
|
the improvements for a release.
|
|
|
|
Issues tagged with these labels have the same priority like issues
|
|
that describe a new feature to be introduced in GitLab, and should be scheduled
|
|
for a release by the appropriate person.
|
|
|
|
Make sure to mention the merge request that the `~"technical debt"` issue or
|
|
`~"UX debt"` issue is associated with in the description of the issue.
|