diff options
Diffstat (limited to 'doc/development/contributing')
| -rw-r--r-- | doc/development/contributing/community_roles.md | 4 | ||||
| -rw-r--r-- | doc/development/contributing/design.md | 18 | ||||
| -rw-r--r-- | doc/development/contributing/issue_workflow.md | 31 | ||||
| -rw-r--r-- | doc/development/contributing/merge_request_workflow.md | 37 | ||||
| -rw-r--r-- | doc/development/contributing/style_guides.md | 9 |
5 files changed, 45 insertions, 54 deletions
diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index 3804aa7f8a8..37c3c24a7d1 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -16,7 +16,3 @@ GitLab community members and their privileges/responsibilities. | Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account | [List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce). - ---- - -[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index c1dd5ff4c0b..9e8375fcbdd 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -11,32 +11,28 @@ For guidance on UX implementation at GitLab, please refer to our [Design System] The UX team uses labels to manage their workflow. -The ~"UX" label on an issue is a signal to the UX team that it will need UX attention. +The `~UX` label on an issue is a signal to the UX team that it will need UX attention. To better understand the priority by which UX tackles issues, see the [UX section](https://about.gitlab.com/handbook/engineering/ux/) of the handbook. -Once an issue has been worked on and is ready for development, a UXer removes the ~"UX" label and applies the ~"UX ready" label to that issue. +Once an issue has been worked on and is ready for development, a UXer removes the `~UX` label and applies the `~"UX ready"` label to that issue. -There is a special type label called ~"product discovery" intended for UX, -PM, FE, and BE. It represents a discovery issue to discuss the problem and +There is a special type label called `~"product discovery"` intended for UX (user experience), +PM (product manager), FE (frontend), and BE (backend). It represents a discovery issue to discuss the problem and potential solutions. The final output for this issue could be a doc of requirements, a design artifact, or even a prototype. The solution will be developed in a subsequent milestone. -~"product discovery" issues are like any other issue and should contain a milestone label, ~"Deliverable" or ~"Stretch", when scheduled in the current milestone. +`~"product discovery"` issues are like any other issue and should contain a milestone label, `~Deliverable` or `~Stretch`, when scheduled in the current milestone. The initial issue should be about the problem we are solving. If a separate [product discovery issue](https://about.gitlab.com/handbook/engineering/ux/ux-department-workflow/#how-we-use-labels) is needed for additional research and design work, it will be created by a PM or UX person. -Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and +Assign the `~UX`, `~"product discovery"` and `~Deliverable` labels, add a milestone and use a title that makes it clear that the scheduled issue is product discovery (for example, `Product discovery for XYZ`). In order to complete a product discovery issue in a release, you must complete the following: -1. UXer removes the ~UX label, adds the ~"UX ready" label. +1. UXer removes the `~UX` label, adds the `~"UX ready"` label. 1. Modify the issue description in the product discovery issue to contain the final design. If it makes sense, the original information indicating the need for the design can be moved to a lower "Original Information" section. 1. Copy the design to the description of the delivery issue for which the product discovery issue was created. Do not simply refer to the product discovery issue as a separate source of truth. 1. In some cases, a product discovery issue also identifies future enhancements that will not go into the issue that originated the product discovery issue. For these items, create new issues containing the designs to ensure they are not lost. Put the issues in the backlog if they are agreed upon as good ideas. Otherwise leave them for triage. - ---- - -[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 1dfe560d68d..29f6eb57160 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -15,9 +15,7 @@ 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/-/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. +The text in the comments (`<!-- ... -->`) is there to help you with what to include. ## Issue triaging @@ -30,12 +28,12 @@ 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/company/team/). -If there is nobody mentioned with that expertise look in the commit history for +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/editpipeline_schedules/10512/edit`, +(`https://gitlab.com/gitlab-org/quality/triage-ops/-/pipeline_schedules/10512/edit`, must have at least the Developer role in the project) running on [quality/triage-ops](https://gitlab.com/gitlab-org/quality/triage-ops) project. @@ -132,9 +130,9 @@ their color is `#A8D695`. <https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml>, with `_` replaced with a space. -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`. +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::). @@ -146,17 +144,6 @@ You can find the groups listed in the [Product Stages, Groups, and Categories](h 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. -Normally there is a 1:1 relationship between Stage labels and Group labels. In -the spirit of "Everyone can contribute", any issue can be picked up by any group, -depending on current priorities. When picking up an issue belonging to a different -group, it should be relabeled. For example, if an issue labeled `~"devops::create"` -and `~"group::knowledge"` is picked up by someone in the Access group of the Plan stage, -the issue should be relabeled as `~"group::access"` while keeping the original -`~"devops::create"` unchanged. - -We also use stage and group labels to help measure our [merge request rates](https://about.gitlab.com/handbook/engineering/metrics/#merge-request-rate). -Please read [Stage and Group labels](https://about.gitlab.com/handbook/engineering/metrics/#stage-and-group-labels) for more information on how the labels are used in this context. - ### Category labels From the handbook's @@ -384,7 +371,7 @@ below will make it easy to manage this, without unnecessary overhead. 1. If you don't agree with a set weight, discuss with other developers until consensus is reached about the weight 1. Issue weights are an abstract measurement of complexity of the issue. Do not - relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring) + relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring_(cognitive_bias)) and something you want to avoid. 1. Something that has a weight of 1 (or no weight) is really small and simple. Something that is 9 is rewriting a large fundamental part of GitLab, @@ -476,7 +463,3 @@ should be of the same quality as those created [in the usual manner](#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. - ---- - -[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 534150e4d37..25561764bd6 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -223,11 +223,19 @@ the contribution acceptance criteria below: ## Definition of done -If you contribute to GitLab please know that changes involve more than just +If you contribute to GitLab, please know that changes involve more than just code. We use the following [definition of done](https://www.agilealliance.org/glossary/definition-of-done). -Your contribution is not *done* until you have made sure it meets all of these +To reach the definition of done, the merge request must create no regressions and meet all these criteria: + +- Verified as working in production on GitLab.com. +- Verified as working for self-managed instances. + +If a regression occurs, we prefer you revert the change. We break the definition of done into two phases: [MR Merge](#mr-merge) and [Production use](#production-use). +Your contribution is *incomplete* until you have made sure it meets all of these requirements. +### MR Merge + 1. Clear description explaining the relevancy of the contribution. 1. Working and clean code that is commented where needed. 1. [Unit, integration, and system tests](../testing_guide/index.md) that all pass @@ -238,17 +246,30 @@ requirements. 1. [Secure coding guidelines](https://gitlab.com/gitlab-com/gl-security/security-guidelines) have been followed. 1. [Documented](../documentation/index.md) in the `/doc` directory. 1. [Changelog entry added](../changelog.md), if necessary. -1. Reviewed by relevant reviewers and all concerns are addressed for Availability, Regressions, Security. Documentation reviews should take place as soon as possible, but they should not block a merge request. -1. Merged by a project maintainer. +1. Reviewed by relevant reviewers, and all concerns are addressed for Availability, Regressions, and Security. Documentation reviews should take place as soon as possible, but they should not block a merge request. +1. The [MR acceptance checklist](../code_review.md#acceptance-checklist) has been checked as confirmed in the MR. 1. Create an issue in the [infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues) to inform the Infrastructure department when your contribution is changing default settings or introduces a new setting, if relevant. -1. Confirmed to be working in the [Canary stage](https://about.gitlab.com/handbook/engineering/#canary-testing) with no new [Sentry](https://about.gitlab.com/handbook/engineering/#sentry) errors or on GitLab.com once the contribution is deployed. -1. Added to the [release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/), - if relevant. -1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml), if relevant. 1. [Black-box tests/end-to-end tests](../testing_guide/testing_levels.md#black-box-tests-at-the-system-level-aka-end-to-end-tests) added if required. Please contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams) with any questions. +1. The change is tested in a review app where possible and if appropriate. 1. The new feature does not degrade the user experience of the product. +1. The change is evaluated to [limit the impact of far-reaching work](https://about.gitlab.com/handbook/engineering/development/#reducing-the-impact-of-far-reaching-work). +1. An agreed-upon rollout plan. +1. Merged by a project maintainer. + +### Production use + +1. Confirmed to be working in staging before implementing the change in production, where possible. +1. Confirmed to be working in the production with no new [Sentry](https://about.gitlab.com/handbook/engineering/#sentry) errors after the contribution is deployed. +1. Confirmed that the rollout plan has been completed. +1. If there is a performance risk in the change, I have analyzed the performance of the system before and after the change. +1. *If the merge request uses feature flags, per-project or per-group enablement, and a staged rollout:* + - Confirmed to be working on GitLab projects. + - Confirmed to be working at each stage for all projects added. +1. Added to the [release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/), + if relevant. +1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml), if relevant. Contributions do not require approval from the [Product team](https://about.gitlab.com/handbook/product/product-processes/#gitlab-pms-arent-the-arbiters-of-community-contributions). diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 1b339b7f252..754e6c7aec6 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -177,11 +177,10 @@ This ensures that our list isn't mistakenly removed by another auto generation o the `.rubocop_todo.yml`. This also allows us greater visibility into the exceptions which are currently being resolved. -One way to generate the initial list is to run the `todo` auto generation, -with `exclude limit` set to a high number. +One way to generate the initial list is to run the Rake task `rubocop:todo:generate`: ```shell -bundle exec rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit=100000 +bundle exec rake rubocop:todo:generate ``` You can then move the list from the freshly generated `.rubocop_todo.yml` for the Cop being actively @@ -242,7 +241,3 @@ See the dedicated [Python Development Guidelines](../python_guide/index.md). ## Misc Code should be written in [US English](https://en.wikipedia.org/wiki/American_English). - ---- - -[Return to Contributing documentation](index.md) |