Add latest changes from gitlab-org/gitlab@master

1 files changed, 325 insertions, 0 deletions

diff --git a/doc/development/labels/index.md b/doc/development/labels/index.md
new file mode 100644
index 00000000000..703a0f3fb95
--- /dev/null
+++ b/doc/development/labels/index.md
@@ -0,0 +1,325 @@
+---
+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.
+
+## 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 add the `~"Pick into X.Y"` label to the merge request, along with the
+  appropriate milestone.
+
+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 `~"good for new contributors"`
+[label](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&state=opened&label_name[]=good%20for%20new%20contributors&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.