Merge branch 'docs-document-category-labels' into 'master'

Improve documentation of stage, group, category, feature labels See merge request gitlab-org/gitlab-ce!32053

Merge branch 'docs-document-category-labels' into 'master'
Improve documentation of stage, group, category, feature labels See merge request gitlab-org/gitlab-ce!32053
26054472 · Achilleas Pipinellis · ec8c9a73 · cc67829a · 26054472 · 26054472
Commit 26054472 authored Aug 27, 2019 by Achilleas Pipinellis
4 changed files
--- a/PROCESS.md
+++ b/PROCESS.md
@@ -267,9 +267,7 @@ The two scenarios below can [bypass the exception request in the release process
 When a bug is found:
 1. Create an issue describing the problem in the most detailed way possible.
 1. If possible, provide links to real examples and how to reproduce the problem.
-1. Label the issue properly, using the [team label](https://docs.gitlab.com/ee/development/contributing/issue_workflow.html#team-labels),
+1. Label the issue properly, by respecting the [Partial triage level](https://about.gitlab.com/handbook/engineering/issue-triage/#partial-triage).
-   the [subject label](https://docs.gitlab.com/ee/development/contributing/issue_workflow.html#subject-labels)
-   and any other label that may apply in the specific case
 1. Notify the respective Engineering Manager to evaluate and apply the [Severity label](https://docs.gitlab.com/ee/development/contributing/issue_workflow.html#severity-labels) and [Priority label](https://docs.gitlab.com/ee/development/contributing/issue_workflow.html#priority-labels).
 The counterpart Product Manager is included to weigh-in on prioritization as needed.
 1. If the ~bug is **NOT** a regression:

--- a/doc/development/contributing/index.md
+++ b/doc/development/contributing/index.md
@@ -93,26 +93,20 @@ When submitting code to GitLab, you may feel that your contribution requires the
 When your code contains more than 500 changes, any major breaking changes, or an external library, `@mention` a maintainer in the merge request. If you are not sure who to mention, the reviewer will add one early in the merge request process.
-## Issues
+## Issues workflow
-This [documentation](issue_workflow.md) outlines the current issue process.
+This [documentation](issue_workflow.md) outlines the current issue workflow:
- [Type labels](issue_workflow.md#type-labels)
+- [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines)
- [Subject labels](issue_workflow.md#subject-labels)
- [Team labels](issue_workflow.md#team-labels)
- [Release Scoping labels](issue_workflow.md#release-scoping-labels)
- [Priority labels](issue_workflow.md#priority-labels)
- [Severity labels](issue_workflow.md#severity-labels)
- [Label for community contributors](issue_workflow.md#label-for-community-contributors)
 - [Issue triaging](issue_workflow.md#issue-triaging)
+- [Labels](issue_workflow.md#labels)
 - [Feature proposals](issue_workflow.md#feature-proposals)
- [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines)
 - [Issue weight](issue_workflow.md#issue-weight)
 - [Regression issues](issue_workflow.md#regression-issues)
 - [Technical and UX debt](issue_workflow.md#technical-and-ux-debt)
- [Stewardship](issue_workflow.md#stewardship)
+- [Technical debt in follow-up issues](issue_workflow.md#technical-debt-in-follow-up-issues)
-## Merge requests
+## Merge requests workflow
 This [documentation](merge_request_workflow.md) outlines the current merge request process.

--- a/doc/development/contributing/issue_workflow.md
+++ b/doc/development/contributing/issue_workflow.md
-# Workflow labels
+# Issues workflow
-To allow for asynchronous issue handling, we use [milestones][milestones-page]
+## Issue tracker guidelines
+**[Search the issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues)** for similar entries before
+submitting your own, there's a good chance somebody else had the same issue or
+feature proposal. Show your support with an award emoji and/or join the
+discussion.
+Please submit bugs using the ['Bug' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Bug.md) provided on the issue tracker.
+The text in the parenthesis is there to help you with what to include. Omit it
+when submitting the actual issue. You can copy-paste it and then edit as you
+see fit.
+## Issue triaging
+Our issue triage policies are [described in our handbook](https://about.gitlab.com/handbook/engineering/issue-triage/).
+You are very welcome to help the GitLab team triage issues.
+We also organize [issue bash events](https://gitlab.com/gitlab-org/gitlab-ce/issues/17815)
+once every quarter.
+The most important thing is making sure valid issues receive feedback from the
+development team. Therefore the priority is mentioning developers that can help
+on those issues. Please select someone with relevant experience from the
+[GitLab team](https://about.gitlab.com/team/).
+If there is nobody mentioned with that expertise look in the commit history for
+the affected files to find someone.
+We also use [GitLab Triage](https://gitlab.com/gitlab-org/gitlab-triage) to
+automate some triaging policies. This is currently set up as a
+[scheduled pipeline](https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/edit)
+running on [quality/triage-ops](https://gitlab.com/gitlab-org/quality/triage-ops) project.
+## 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-ce/-/labels). Leads and product managers handle most of the
 scheduling into milestones. Labelling is a task for everyone.
 Most issues will have labels for at least one of the following:
 - Type: ~feature, ~bug, ~backstage, etc.
- Subject: ~wiki, ~"Container Registry", ~ldap, ~api, etc.
- Team: ~Documentation, ~Delivery, etc.
 - Stage: ~"devops::plan", ~"devops::create", etc.
- Group: ~"group::source code" ~"group::knowledge" ~"group::editor", etc.
+- Group: ~"group::source code", ~"group::knowledge", ~"group::editor", etc.
+- Category: ~"Category:Code Analytics", ~"Category:DevOps Score", ~"Category:Templates", etc.
+- Feature: ~wiki, ~ldap, ~api, ~issues, ~"merge requests", etc.
 - Department: ~UX, ~Quality
+- Team: ~Documentation, ~Delivery
 - Specialization: ~frontend, ~backend
 - Release Scoping: ~Deliverable, ~Stretch, ~"Next Patch Release"
 - Priority: ~P1, ~P2, ~P3, ~P4
@@ -23,14 +57,18 @@ All labels, their meaning and priority are defined on the
 If you come across an issue that has none of these, and you're allowed to set
 labels, you can _always_ add the team and type, and often also the subject.
-[milestones-page]: https://gitlab.com/groups/gitlab-org/-/milestones
+### Type labels
-## Type labels
 Type labels are very important. They define what kind of issue this is. Every
-issue should have one or more.
+issue should have one and only one.
+The current type labels are:
-Examples of type labels are ~feature, ~bug, ~backstage and ~security
+- ~feature
+- ~bug
+- ~backstage
+- ~"support request"
+- ~meta
 A number of type labels have a priority assigned to them, which automatically
 makes them float to the top, depending on their importance.
@@ -38,68 +76,74 @@ 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 subject labels).
-The descriptions on the [labels page](https://gitlab.com/gitlab-org/gitlab-ce/-/labels) explain what falls under each type label.
+The descriptions on the [labels page](https://gitlab.com/groups/gitlab-org/-/labels)
+explain what falls under each type label.
-## Subject labels
+### Facet labels
-Subject labels are labels that define what area or feature of GitLab this issue
+Sometimes it's useful to refine the type of an issue. In those cases, you can
-hits. They are not always necessary, but very convenient.
+add facet labels.
-Subject labels are now used to infer and apply relevant group and devops stage
+Following is a non-exhaustive list of facet labels:
-labels. Please apply them whenever possible to facilitate accurate matching.
-Please refer to [this merge request][inferred-labels] for more information.
-Examples of subject labels are ~wiki, ~ldap, ~api,
+- ~enhancement: This label can refine an issue that has the ~feature label.
-~issues, ~"merge requests", ~labels, and ~"Container Registry".
+- ~"master:broken": This label can refine an issue that has the ~bug label.
+- ~"master:flaky": This label can refine an issue that has the ~bug label.
+- ~"technical debt": This label can refine an issue that has the ~backstage label.
+- ~"static analysis": This label can refine an issue that has the ~backstage label.
+- ~"ci-build": This label can refine an issue that has the ~backstage label.
+- ~performance: A performance issue could describe a ~bug or a ~feature.
+- ~security: A security issue could describe a ~bug or a ~feature.
+- ~database: A database issue could describe a ~bug or a ~feature.
+- ~customer: This relates to an issue that was created by a customer, or that is of interest for a customer.
-If you are an expert in a particular area, it makes it easier to find issues to
+### Stage labels
-work on. You can also subscribe to those labels to receive an email each time an
-issue is labeled with a subject label corresponding to your expertise.
-Subject labels are always all-lowercase.
+Stage labels specify which [stage](https://about.gitlab.com/handbook/product/categories/#hierarchy) the issue belongs to.
-## Team labels
+#### Naming and color convention
-**Important**: Most of the historical team labels (e.g. Manage, Plan etc.) 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:
+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 ` `.
- ~Delivery
+For instance, the "Manage" stage is represented by the ~"devops::manage" label in
- ~Documentation
+the `gitlab-org` group since its key under `stages` is `manage`.
- ~Quality
-Team labels are always capitalized so that they show up as the first label for
+The current stage labels can be found by [searching the labels list for `devops::`](https://gitlab.com/groups/gitlab-org/-/labels?search=devops::).
-any issue.
-## Stage labels
+These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium)
+and thus are mutually exclusive.
-Stage labels specify which [DevOps stage][devops-stages] the issue belongs to.
+The Stage labels are used to generate the [direction pages](https://about.gitlab.com/direction/) automatically.
-The current stage labels can be found by [searching the labels list for `devops::`](https://gitlab.com/groups/gitlab-org/-/labels?search=devops%3A%3A).
+### Group labels
-These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium)
+Group labels specify which [groups](https://about.gitlab.com/company/team/structure/#product-groups) the issue belongs to.
-and thus are mutually exclusive.
-The Stage labels are used to generate the [direction pages][direction-pages] automatically.
+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).
-[devops-stages]: https://about.gitlab.com/direction/#devops-stages
+#### Naming and color convention
-[direction-pages]: https://about.gitlab.com/direction/
-## Group labels
+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 ` `.
-Group labels specify which [groups][structure-groups] the issue belongs to.
+For instance, the "Continuous Integration" group is represented by the
+~"group::continuous integration"  label in the `gitlab-org` group since its key
+under `stages.manage.groups` is `continuous_integration`.
-The current group labels can be found by [searching the labels list for `group::`](https://gitlab.com/groups/gitlab-org/-/labels?search=group%3A%3A).
+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-premium)
 and thus are mutually exclusive.
-You can find the groups listed in the [Product Stages, Groups, and Categories][product-categories] page.
+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.
@@ -110,24 +154,95 @@ any issue can be picked up by any group, depending on current priorities. For ex
 We also use stage and group labels to help quantify our [throughput](https://about.gitlab.com/handbook/engineering/management/throughput).
 Please read [Stage and Group labels in Throughtput](https://about.gitlab.com/handbook/engineering/management/throughput/#stage-and-group-labels-in-throughput) for more information on how the labels are used in this context.
-[structure-groups]: https://about.gitlab.com/company/team/structure/#groups
+### Category labels
-[product-categories]: https://about.gitlab.com/handbook/product/categories/
+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. e.g. Portfolio Management.
+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 "Code Analytics" category is represented by the
+~"Category:Code Analytics" label in the `gitlab-org` group since its
+`code_analytics.name` value is "Code Analytics".
+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/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. e.g. 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, ~"merge requests" etc.
+#### Naming and color convention
-## Department labels
+Feature labels are all-lowercase.
+### Department labels
 The current department labels are:
 - ~UX
 - ~Quality
-## Specialization labels
+### Team labels
+**Important**: Most of the historical team labels (e.g. Manage, Plan etc.) 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
+- ~Documentation
+#### 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
-## Release Scoping labels
+### 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:
@@ -145,7 +260,7 @@ 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
+#### Priority labels
 Priority labels help us define the time a ~bug fix should be completed. Priority determines how quickly the defect turnaround time must be.
 If there are multiple defects, the priority decides which defect has to be fixed immediately versus later.
@@ -158,7 +273,7 @@ This label documents the planned timeline & urgency which is used to measure aga
 | ~P3   | Medium Priority | Within the next 3 releases (approx one quarter or 90 days)                 |
 | ~P4   | Low Priority    | Anything outside the next 3 releases (more than one quarter or 120 days)   |
-## Severity labels
+### Severity labels
 Severity labels help us clearly communicate the impact of a ~bug on users.
 There can be multiple facets of the impact. The below is a guideline.
@@ -187,7 +302,7 @@ If a bug seems to fall between two severity labels, assign it to the higher-seve
  - Label colors are incorrect.
  - UI elements are not fully aligned.
-## Label for community contributors
+### Label for community contributors
 Issues that are beneficial to our users, 'nice to haves', that we currently do
 not have the capacity for or want to give the priority to, are labeled as
@@ -217,11 +332,11 @@ After adding the ~"Accepting merge requests" label, we try to estimate the
 [weight](#issue-weight) of the issue. We use issue weight to let contributors
 know how difficult the issue is. Additionally:
- We advertise [`Accepting merge requests` issues with weight < 5][up-for-grabs]
+- We advertise [`Accepting merge requests` issues with weight < 5](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight)
  as suitable for people that have never contributed to GitLab before on the
  [Up For Grabs campaign](http://up-for-grabs.net)
 - We encourage people that have never contributed to any open source project to
-  look for [`Accepting merge requests` issues with a weight of 1][first-timers]
+  look for [`Accepting merge requests` issues with a weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1)
 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)
@@ -234,42 +349,29 @@ GitLab team members who apply the ~"Accepting merge requests" label to an issue
 should update the issue description with a responsible product manager, inviting
 any potential community contributor to @-mention per above.
-[up-for-grabs]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight
+### Stewardship label
-[first-timers]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1
-## Issue triaging
-Our issue triage policies are [described in our handbook]. You are very welcome
-to help the GitLab team triage issues. We also organize [issue bash events] once
-every quarter.
-The most important thing is making sure valid issues receive feedback from the
+For issues related to the open source stewardship of GitLab,
-development team. Therefore the priority is mentioning developers that can help
+there is the ~"stewardship" label.
-on those issues. Please select someone with relevant experience from the
-[GitLab team][team]. If there is nobody mentioned with that expertise look in
-the commit history for the affected files to find someone.
-We also use [GitLab Triage] to automate some triaging policies. This is
+This label is to be used for issues in which the stewardship of GitLab
-currently set up as a [scheduled pipeline] running on [quality/triage-ops]
+is a topic of discussion. For instance if GitLab Inc. is planning to add
-project.
+features from GitLab EE to GitLab CE, related issues would be labelled with
+~"stewardship".
-[described in our handbook]: https://about.gitlab.com/handbook/engineering/issue-triage/
+A recent example of this was the issue for
-[issue bash events]: https://gitlab.com/gitlab-org/gitlab-ce/issues/17815
+[bringing the time tracking API to GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce/issues/25517#note_20019084).
-[GitLab Triage]: https://gitlab.com/gitlab-org/gitlab-triage
-[scheduled pipeline]: https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/edit
-[quality/triage-ops]: https://gitlab.com/gitlab-org/quality/triage-ops
-[team]: https://about.gitlab.com/team/
 ## Feature proposals
 To create a feature proposal for CE, open an issue on the
-[issue tracker of CE][ce-tracker].
+[issue tracker of CE](https://gitlab.com/gitlab-org/gitlab-ce/issues).
 For feature proposals for EE, open an issue on the
-[issue tracker of EE][ee-tracker].
+[issue tracker of EE](https://gitlab.com/gitlab-org/gitlab-ee/issues).
 In order to help track the feature proposals, we have created a
-[`feature`][fl] label. For the time being, users that are not members
+[`feature`](https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature) label. For the time being, users that are not members
 of the project cannot add labels. You can instead ask one of the [core team](https://about.gitlab.com/community/core-team/)
 members to add the label ~feature to the issue or add the following
 code snippet right after your description in a new line: `~feature`.
@@ -286,20 +388,6 @@ need to ask one of the [core team](https://about.gitlab.com/community/core-team/
 If you want to create something yourself, consider opening an issue first to
 discuss whether it is interesting to include this in GitLab.
-[fl]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature
-## Issue tracker guidelines
-**[Search the issue tracker][ce-tracker]** for similar entries before
-submitting your own, there's a good chance somebody else had the same issue or
-feature proposal. Show your support with an award emoji and/or join the
-discussion.
-Please submit bugs using the ['Bug' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Bug.md) provided on the issue tracker.
-The text in the parenthesis is there to help you with what to include. Omit it
-when submitting the actual issue. You can copy-paste it and then edit as you
-see fit.
 ## Issue weight
 Issue weight allows us to get an idea of the amount of work required to solve
@@ -345,7 +433,7 @@ addressed.
 ## Technical and UX debt
 In order to track things that can be improved in GitLab's codebase,
-we use the ~"technical debt" label in [GitLab's issue tracker][ce-tracker].
+we use the ~"technical debt" label in [GitLab's issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues).
 For missed user experience requirements, we use the ~"UX debt" label.
 These labels should be added to issues that describe things that can be improved,
@@ -406,25 +494,6 @@ should be of the same quality as those created
 **must not** begin with `Follow-up`! The creating maintainer should also expect
 to be involved in some capacity when work begins on the follow-up issue.
-## Stewardship
-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 labelled with
-~"stewardship".
-A recent example of this was the issue for
-[bringing the time tracking API to GitLab CE][time-tracking-issue].
-[time-tracking-issue]: https://gitlab.com/gitlab-org/gitlab-ce/issues/25517#note_20019084
 ---
 [Return to Contributing documentation](index.md)
-[ce-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues
-[ee-tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues
-[inferred-labels]: https://gitlab.com/gitlab-org/quality/triage-ops/merge_requests/155
--- a/doc/development/contributing/merge_request_workflow.md
+++ b/doc/development/contributing/merge_request_workflow.md
-# Merge requests
+# Merge requests workflow
 We welcome merge requests from everyone, with fixes and improvements
 to GitLab code, tests, and documentation. The issues that are specifically suitable