Commit 14457da2 authored by Rémy Coutable's avatar Rémy Coutable

Consolidate Doc approvals guideline in doc/development/code_review.md

Signed-off-by: default avatarRémy Coutable <remy@rymai.me>
parent c901cb74
......@@ -73,6 +73,9 @@ from teams other than your own.
**approved by a [UX lead](https://about.gitlab.com/company/team/)**.
1. If your merge request includes a new dependency or a filesystem change, it must be
**approved by a [Distribution team member](https://about.gitlab.com/company/team/)**. See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/#how-to-work-with-distribution) for more details.
1. If your merge request includes documentation changes, it must be **approved
by a [Technical writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers)**, based on
the appropriate [product category](https://about.gitlab.com/handbook/product/categories/).
#### Security requirements
......@@ -84,12 +87,17 @@ The responsibility to find the best solution and implement it lies with the
merge request author.
Before assigning a merge request to a maintainer for approval and merge, they
should be confident that it actually solves the problem it was meant to solve,
that it does so in the most appropriate way, that it satisfies all requirements,
and that there are no remaining bugs, logical problems, uncovered edge cases,
or known vulnerabilities. The best way to do this, and to avoid unnecessary
back-and-forth with reviewers, is to perform a self-review of your own merge
request, following the [Code Review](#reviewing-a-merge-request) guidelines.
should be confident that:
- It actually solves the problem it was meant to solve.
- It does so in the most appropriate way.
- It satisfies all requirements.
- There are no remaining bugs, logical problems, uncovered edge cases,
or known vulnerabilities.
The best way to do this, and to avoid unnecessary back-and-forth with reviewers,
is to perform a self-review of your own merge request, following the
[Code Review](#reviewing-a-merge-request) guidelines.
To reach the required level of confidence in their solution, an author is expected
to involve other people in the investigation and implementation processes as
......@@ -110,11 +118,11 @@ request diff alerting the reviewer to anything important as well as for anything
that demands further explanation or attention. Examples of content that may
warrant a comment could be:
- The addition of a linting rule (Rubocop, JS etc)
- The addition of a library (Ruby gem, JS lib etc)
- Where not obvious, a link to the parent class or method
- Any benchmarking performed to complement the change
- Potentially insecure code
- The addition of a linting rule (Rubocop, JS etc).
- The addition of a library (Ruby gem, JS lib etc).
- Where not obvious, a link to the parent class or method.
- Any benchmarking performed to complement the change.
- Potentially insecure code.
Avoid:
......@@ -233,6 +241,11 @@ first time.
addressed. If there's an open reply, an open thread, a suggestion,
a question, or anything else, the thread should be left to be resolved
by the reviewer.
- It should not be assumed that all feedback requires their recommended changes
to be incorporated into the MR before it is merged. It is a judgment call by
the MR author and the reviewer as to if this is required, or if a follow-up
issue should be created to address the feedback in the future after the MR in
question is merged.
- Push commits based on earlier rounds of feedback as isolated commits to the
branch. Do not squash until the branch is ready to merge. Reviewers should be
able to read individual updates based on their earlier feedback.
......
......@@ -48,13 +48,8 @@ request is as follows:
but do not change the commit history if you're working on shared branches though.
1. Push the commit(s) to your working branch in your fork.
1. Submit a merge request (MR) to the `master` branch in the main GitLab project.
1. Your merge request needs at least 1 approval, but feel free to require more.
For instance if you're touching both backend and frontend code, it's a good idea
to require 2 approvals: 1 from a backend maintainer and 1 from a frontend
maintainer.
1. If you're submitting changes to documentation, you'll need approval from a technical
writer, based on the appropriate [product category](https://about.gitlab.com/handbook/product/categories/).
Only assign the MR to them when it's ready for docs review.
1. Your merge request needs at least 1 approval, but depending on your changes
you might need additional approvals. Refer to the [Approval guidelines](../code_review.md#approval-guidelines).
1. You don't have to select any specific approvers, but you can if you really want
specific people to approve your merge request.
1. The MR title should describe the change you want to make.
......@@ -66,18 +61,12 @@ request is as follows:
1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or
`Closes #XXX` syntax to [auto-close](../../user/project/issues/managing_issues.md#closing-issues-automatically)
the issue(s) once the merge request is merged.
1. If you're allowed to (Core team members, for example), set a relevant milestone
and [labels](issue_workflow.md).
1. If the MR changes the UI, you'll need approval from a Product Designer (UX), based on the appropriate [product category](https://about.gitlab.com/handbook/product/categories/). UI changes should use available components from the GitLab Design System, [Pajamas](https://design.gitlab.com/). The MR must include *Before* and *After* screenshots.
1. If you're allowed to, set a relevant milestone and [labels](issue_workflow.md).
1. UI changes should use available components from the GitLab Design System,
[Pajamas](https://design.gitlab.com/). The MR must include *Before* and
*After* screenshots.
1. If the MR changes CSS classes, please include the list of affected pages, which
can be found by running `grep css-class ./app -R`.
1. Be prepared to answer questions and incorporate feedback into your MR with new
commits. Once you have fully addressed a suggestion from a reviewer, click the
"Resolve thread" button beneath it to mark it resolved.
1. The merge request author resolves only the threads they have fully addressed.
If there's an open reply or thread, a suggestion, a question, or anything else,
the thread should be left to be resolved by the reviewer.
1. It should not be assumed that all feedback requires their recommended changes to be incorporated into the MR before it is merged. It is a judgment call by the MR author and the reviewer as to if this is required, or if a follow-up issue should be created to address the feedback in the future after the MR in question is merged.
1. If your MR touches code that executes shell commands, reads or opens files, or
handles paths to files on disk, make sure it adheres to the
[shell command guidelines](../shell_commands.md)
......@@ -98,6 +87,10 @@ request is as follows:
`doc/update/upgrading_from_source.md` in the same merge request. If these
instructions are specific to a version, add them to the "Version specific
upgrading instructions" section.
1. Read and adhere to
[The responsibility of the merge request author](../code_review.md#the-responsibility-of-the-merge-request-author).
1. Read and follow
[Having your merge request reviewed](../code_review.md#having-your-merge-request-reviewed).
If you would like quick feedback on your merge request feel free to mention someone
from the [core team](https://about.gitlab.com/community/core-team/) or one of the
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment