diff --git a/doc/development/code_review.md b/doc/development/code_review.md index c7811e165513df46352b2c37e37a4564fcae604b..0f169447ade5bc67b2491c72269c067e6befff0c 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -237,7 +237,7 @@ See the [test engineering process](https://about.gitlab.com/handbook/engineering ##### Compliance -1. You have confirmed that the correct [MR type label](contributing/issue_workflow.md#type-labels) has been applied. +1. You have confirmed that the correct [MR type label](labels/index.md) has been applied. ### The responsibility of the merge request author @@ -532,7 +532,7 @@ WARNING: Before taking the decision to merge: - Set the milestone. -- Confirm that the correct [MR type label](contributing/issue_workflow.md#type-labels) is applied. +- Confirm that the correct [MR type label](labels/index.md#type-labels) is applied. - Consider warnings and errors from danger bot, code quality, and other reports. Unless a strong case can be made for the violation, these should be resolved before merging. A comment must be posted if the MR is merged with any failed job. diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index cff184380d0331853bc979ecdfa8396f5754fc80..210370f98166d5dab794a61b09d0b3bd31dc909c 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -127,7 +127,7 @@ At any moment, but usually _during_ or _after_ the design's implementation: - Contribute [issues to Pajamas](https://design.gitlab.com/get-started/contributing#contribute-an-issue) for additions or enhancements to the design system. -- Create issues with the [`~UX debt`](issue_workflow.md#technical-and-ux-debt) +- Create issues with the [`~UX debt`](../labels/index.md#technical-and-ux-debt) label for intentional deviations from the agreed-upon UX requirements due to time or feasibility challenges, linking back to the corresponding issues or merge requests. diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 1a169b05eed129d0fa390f3bde63dee7812d4d85..cf10a10611987943fe6d24631eb3940b185fcefd 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -36,7 +36,7 @@ for audiences of all ages. If you would like to contribute to GitLab: - Issues with the - [`~Seeking community contributions` label](issue_workflow.md#label-for-community-contributors) + [`~Seeking community contributions` label](../labels/index.md#label-for-community-contributors) are a great place to start. - Optimizing our tests is another great opportunity to contribute. You can use [RSpec profiling statistics](https://gitlab-org.gitlab.io/rspec_profiling_stats/) to identify @@ -112,11 +112,11 @@ working days of its initial submission, you can ask for help with `@gitlab-bot h This [documentation](issue_workflow.md) outlines the current issue workflow: - [Issue triaging](issue_workflow.md#issue-triaging) -- [Labels](issue_workflow.md#labels) +- [Labels](../labels/index.md) - [Feature proposals](issue_workflow.md#feature-proposals) - [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) +- [Technical and UX debt](../labels/index.md#technical-and-ux-debt) - [Technical debt in follow-up issues](issue_workflow.md#technical-debt-in-follow-up-issues) #### Merge requests workflow diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index b55fef25302ef5cd81d0c9c201974553d5b366b5..583b39ebe564856647e4c12b41d66f20d7af1741 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -37,300 +37,7 @@ the affected files to find someone. We also have triage automation in place, described [in our handbook](https://about.gitlab.com/handbook/engineering/quality/triage-operations/). -## 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). +For information about which labels to apply to issues, see [Labels](../labels/index.md). ## Feature proposals @@ -399,31 +106,6 @@ The release manager will [update the notes](https://gitlab.com/gitlab-org/release-tools/blob/master/doc/pro-tips.md#update-the-regression-issue) in the regression issue as fixes are addressed. -## 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. - ## Technical debt in follow-up issues It's common to discover technical debt during development of a new feature. In @@ -459,6 +141,6 @@ and assignee. The maintainer must always agree before an outstanding discussion is resolved in this manner, and will be the one to create the issue. The title and description should be of the same quality as those created -[in the usual manner](#technical-and-ux-debt) - in particular, the issue title +[in the usual manner](../labels/index.md#technical-and-ux-debt) - in particular, the issue title **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. diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 16a7244162cb356e64c731cfa0888063d38dc79b..c9866131cc7eab931409de672ee6679b50fb7589 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w We welcome merge requests from everyone, with fixes and improvements to GitLab code, tests, and documentation. The issues that are specifically suitable -for community contributions have the [`Seeking community contributions`](issue_workflow.md#label-for-community-contributors) +for community contributions have the +[`Seeking community contributions`](../labels/index.md#label-for-community-contributors) label, but you are free to contribute to any issue you want. ## Working from issues diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 63612861e4defa4166819635a00d5e1eb31da5a9..07ad07375e2666e98f197c061b83c748d8665502 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -83,16 +83,16 @@ If you are a member of the GitLab Slack workspace, you can request help in `#doc When you author an issue or merge request, you must add these labels: -- A [type label](../contributing/issue_workflow.md#type-labels), either `~"type::feature"` or `~"type::maintenance"`. -- A [stage label](../contributing/issue_workflow.md#stage-labels) and [group label](../contributing/issue_workflow.md#group-labels). +- A [type label](../labels/index.md#type-labels), either `~"type::feature"` or `~"type::maintenance"`. +- A [stage label](../labels/index.md#stage-labels) and [group label](../labels/index.md#group-labels). For example, `~devops::create` and `~group::source code`. -- A `~documentation` [specialization label](../contributing/issue_workflow.md#specialization-labels). +- A `~documentation` [specialization label](../labels/index.md#specialization-labels). A member of the Technical Writing team adds these labels: - A [documentation scoped label](../../user/project/labels.md#scoped-labels) with the `docs::` prefix. For example, `~docs::improvement`. -- The [`~Technical Writing` team label](../contributing/issue_workflow.md#team-labels). +- The [`~Technical Writing` team label](../labels/index.md#team-labels). ## Reviewing and merging diff --git a/doc/development/labels/index.md b/doc/development/labels/index.md new file mode 100644 index 0000000000000000000000000000000000000000..703a0f3fb95ba64e98cbcfd095e46ce26944b020 --- /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. diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index fcb6e5c1b20f9d9de6625d8ccd3c7bddf65f6658..eed9f006bfac61a793b45d0f81a8016dd31a156f 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -110,9 +110,9 @@ The decision on whether backporting a change is performed is done at the discret [current release managers](https://about.gitlab.com/community/release-managers/), based on *all* of the following: -1. Estimated [severity](../development/contributing/issue_workflow.md#severity-labels) of the bug: +1. Estimated [severity](../development/labels/index.md#severity-labels) of the bug: Highest possible impact to users based on the current definition of severity. -1. Estimated [priority](../development/contributing/issue_workflow.md#priority-labels) of the bug: +1. Estimated [priority](../development/labels/index.md#priority-labels) of the bug: Immediate impact on all impacted users based on the above estimated severity. 1. Potentially incurring data loss and/or security breach. 1. Potentially affecting one or more strategic accounts due to a proven inability by the user to upgrade to the current stable version. @@ -122,7 +122,7 @@ the current stable release, and two previous monthly releases. In rare cases a r For instance, if we release `13.2.1` with a fix for a severe bug introduced in `13.0.0`, we could backport the fix to a new `13.0.x`, and `13.1.x` patch release. -Note that [severity](../development/contributing/issue_workflow.md#severity-labels) 3 and lower +Note that [severity](../development/labels/index.md#severity-labels) 3 and lower requests are automatically turned down. To request backporting to more than one stable release for consideration, raise an issue in the diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index e6fb994d9b71f5012cd0c8fe1776ac95c5802a9c..e52d1755956f97f79b2c0c4f8e1d363b3def02d4 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -2702,7 +2702,7 @@ You can expedite the investigation with the [testssl.sh tool](https://testssl.sh To get support for your particular problem use the [getting help channels](https://about.gitlab.com/get-help/). The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and API Fuzzing. -Use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding API fuzzing to ensure it is quickly reviewed by the right people. Refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. +Use `~"Category:API Security"` [label](../../../development/labels/index.md) when opening a new issue regarding API fuzzing to ensure it is quickly reviewed by the right people. Refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. [Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/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. diff --git a/doc/user/application_security/api_security/api_discovery/index.md b/doc/user/application_security/api_security/api_discovery/index.md index e916bf879cfc085ea664cbaba663742fb8d3311f..6e47531166369e119bc73b39196b76be6c944357 100644 --- a/doc/user/application_security/api_security/api_discovery/index.md +++ b/doc/user/application_security/api_security/api_discovery/index.md @@ -154,7 +154,7 @@ TODO To get support for your particular problem, use the [getting help channels](https://about.gitlab.com/get-help/). The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Discovery. -Use `~"Category:API Security"` [label](../../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding API Discovery to ensure it is quickly reviewed by the right people. Refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. +Use `~"Category:API Security"` [label](../../../../development/labels/index.md) when opening a new issue regarding API Discovery to ensure it is quickly reviewed by the right people. Refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. [Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/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. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index c663beab2e54bf5f9dfc3f02acb523742bf6f7c1..ff2a5b3a0695c584c0b749fc7e06fedbb84d3177 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -2558,7 +2558,7 @@ You can expedite the investigation with the [testssl.sh tool](https://testssl.sh To get support for your particular problem, use the [getting help channels](https://about.gitlab.com/get-help/). The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and DAST API. -Use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. +Use `~"Category:API Security"` [label](../../../development/labels/index.md) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. [Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/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.