diff options
| -rw-r--r-- | PROCESS.md | 4 | ||||
| -rw-r--r-- | doc/development/contributing/index.md | 18 | ||||
| -rw-r--r-- | doc/development/contributing/issue_workflow.md | 295 | ||||
| -rw-r--r-- | doc/development/contributing/merge_request_workflow.md | 2 |
4 files changed, 181 insertions, 138 deletions
diff --git a/PROCESS.md b/PROCESS.md index 22b68b0aaca..f0a82838f62 100644 --- 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), - 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. Label the issue properly, by respecting the [Partial triage level](https://about.gitlab.com/handbook/engineering/issue-triage/#partial-triage). 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: diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 853882e8642..3637a08c3cd 100644 --- 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) -- [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 tracker guidelines](issue_workflow.md#issue-tracker-guidelines) - [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. diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index b2e3ef7bf63..64fbc997b45 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -1,17 +1,51 @@ -# 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. -Examples of type labels are ~feature, ~bug, ~backstage and ~security +The current type labels are: + +- ~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,56 @@ 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. - -## Subject labels - -Subject labels are labels that define what area or feature of GitLab this issue -hits. They are not always necessary, but very convenient. - -Subject labels are now used to infer and apply relevant group and devops stage -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, -~issues, ~"merge requests", ~labels, and ~"Container Registry". - -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 subject label corresponding to your expertise. - -Subject labels are always all-lowercase. +The descriptions on the [labels page](https://gitlab.com/groups/gitlab-org/-/labels) +explain what falls under each type label. -## Team labels +### Stage 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). +Stage labels specify which [stage](https://about.gitlab.com/handbook/product/categories/#hierarchy) the issue belongs to. -Team labels specify what team is responsible for this issue. -Assigning a team label makes sure issues get the attention of the appropriate -people. +#### Naming and color convention -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 -- ~Documentation -- ~Quality +For instance, the "Manage" stage is represented by the ~"devops::manage" label in +the `gitlab-org` group since its key under `stages` is `manage`. -Team labels are always capitalized so that they show up as the first label for -any issue. +The current stage labels can be found by [searching the labels list for `devops::`](https://gitlab.com/groups/gitlab-org/-/labels?search=devops::). -## 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) -and thus are mutually exclusive. +Group labels specify which [groups](https://about.gitlab.com/company/team/structure/#product-groups) the issue belongs to. -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 -[direction-pages]: https://about.gitlab.com/direction/ +#### Naming and color convention -## 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 +136,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 -[product-categories]: https://about.gitlab.com/handbook/product/categories/ +### 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. 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 +242,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 +255,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 +284,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 +314,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 +331,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 -[first-timers]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1 +### Stewardship label -## 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 -development team. Therefore the priority is mentioning developers that can help -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. +For issues related to the open source stewardship of GitLab, +there is the ~"stewardship" label. -We also use [GitLab Triage] to automate some triaging policies. This is -currently set up as a [scheduled pipeline] running on [quality/triage-ops] -project. +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". -[described in our handbook]: https://about.gitlab.com/handbook/engineering/issue-triage/ -[issue bash events]: https://gitlab.com/gitlab-org/gitlab-ce/issues/17815 -[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/ +A recent example of this was the issue for +[bringing the time tracking API to GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce/issues/25517#note_20019084). ## 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 +370,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 +415,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 +476,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 diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 4e9c5c81379..bdb026d498d 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -1,4 +1,4 @@ -# 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 |