diff options
Diffstat (limited to 'doc/user/project/merge_requests')
52 files changed, 1371 insertions, 1019 deletions
diff --git a/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v13_3.png b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png Binary files differindex 306bf57354d..306bf57354d 100644 --- a/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v13_3.png +++ b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png diff --git a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_7.png b/doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png Binary files differindex 669148a41d8..669148a41d8 100644 --- a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_7.png +++ b/doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png diff --git a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png b/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png Binary files differindex a6636f0bc7f..a6636f0bc7f 100644 --- a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png +++ b/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png b/doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png Binary files differindex c5596b965ff..c5596b965ff 100644 --- a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png +++ b/doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md new file mode 100644 index 00000000000..ac48e44da52 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/index.md @@ -0,0 +1,145 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html' +--- + +# Merge request approvals **(FREE)** + +> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. + +You can configure your merge requests so that they must be approved before +they can be merged. You can do this by creating [rules](rules.md) or by specifying +a list of users who act as [code owners](../../code_owners.md) for specific files. + +You can configure merge request approvals for each project. In higher GitLab tiers, +Administrators of self-managed GitLab instances can configure approvals +[for the entire instance](../../../admin_area/merge_requests_approvals.md). + +## How approvals work + +With [merge request approval rules](rules.md), you can set the minimum number of +required approvals before work can merge into your project. You can also extend these +rules to define what types of users can approve work. Some examples of rules you can create include: + +- Users with specific permissions can always approve work. +- [Code owners](../../code_owners.md) can approve work for files they own. +- Users with specific permissions can approve work, + [even if they don't have merge rights](rules.md#merge-request-approval-segregation-of-duties) + to the repository. +- Users with specific permissions can be allowed or denied the ability + to [override approval rules on a specific merge request](rules.md#edit-or-override-merge-request-approval-rules). + +You can also configure additional [settings for merge request approvals](settings.md) +for more control of the level of oversight and security your project needs, including: + +- [Prevent users from overriding a merge request approval rule.](settings.md#prevent-overrides-of-default-approvals) +- [Reset approvals when new code is pushed.](settings.md#reset-approvals-on-push) +- Allow (or disallow) [authors and committers](settings.md) to approve their own merge requests. +- [Require password authentication when approving.](settings.md#require-authentication-for-approvals) +- [Require security team approval.](settings.md#security-approvals-in-merge-requests) + +You can configure your merge request approval rules and settings through the GitLab +user interface or [with the API](../../../../api/merge_request_approvals.md). + +## Approve a merge request + +When an [eligible approver](rules.md#eligible-approvers) visits an open merge request, +GitLab displays one of these buttons after the body of the merge request: + +- **Approve**: The merge request doesn't yet have the required number of approvals. +- **Approve additionally**: The merge request has the required number of approvals. +- **Revoke approval**: The user viewing the merge request has already approved + the merge request. + +Eligible approvers can also use the `/approve` +[quick action](../../../project/quick_actions.md) when adding a comment to +a merge request. + +After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge +unless it's blocked for another reason. Merge requests can be blocked by other problems, +such as merge conflicts, [pending discussions](../../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), +or a [failed CI/CD pipeline](../merge_when_pipeline_succeeds.md). + +To prevent merge request authors from approving their own merge requests, +enable [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) +in your project's settings. + +If you enable [approval rule overrides](settings.md#prevent-overrides-of-default-approvals), +merge requests created before a change to default approval rules are not affected. +The only exceptions are changes to the [target branch](rules.md#approvals-for-protected-branches) +of the rule. + +## Optional approvals + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. + +GitLab allows all users with Developer or greater [permissions](../../../permissions.md) +to approve merge requests. Approvals in GitLab Free are optional, and don't prevent +a merge request from merging without approval. + +## Required approvals **(PREMIUM)** + +> Moved to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.9. + +Required approvals enforce code reviews by the number and type of users you specify. +Without the approvals, the work cannot merge. Required approvals enable multiple use cases: + +- Enforce review of all code that gets merged into a repository. +- Specify reviewers for a given proposed code change, and a minimum number + of reviewers, through [Approval rules](rules.md). +- Specify categories of reviewers, such as backend, frontend, quality assurance, or + database, for all proposed code changes. +- Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), + to determine who should review the work. +- [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) + before merging code that could introduce a vulnerability. **(ULTIMATE)** + +## Notify external services **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. +> - [Deployed behind a feature flag](../../../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can create an external approval rule to integrate approvals with third-party tools. +When users create, change, or close merge requests, GitLab sends a notification. +The users of the third-party tools can then approve merge requests from outside of GitLab. + +With this integration, you can integrate with third-party workflow tools, like +[ServiceNow](https://www.servicenow.co.uk/), or the custom tool of your choice. +You can modify your external approval rules +[by using the REST API](../../../../api/merge_request_approvals.md#external-project-level-mr-approvals). + +The lack of an external approval doesn't block the merging of a merge request. + +When [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, +changes to default approval rules will **not** be applied to existing +merge requests, except for changes to the [target branch](rules.md#approvals-for-protected-branches) +of the rule. + +To learn more about use cases, feature discovery, and development timelines, +see the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). + +## Related links + +- [Merge request approvals API](../../../../api/merge_request_approvals.md) +- [Instance-level approval rules](../../../admin_area/merge_requests_approvals.md) for self-managed installations + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md new file mode 100644 index 00000000000..32f0160771f --- /dev/null +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -0,0 +1,232 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +--- + +# Merge request approval rules + +Approval rules define how many [approvals](index.md) a merge request must receive before it can +be merged, and which users should do the approving. You can define approval rules: + +- [As project defaults](#add-an-approval-rule). +- [Per merge request](#edit-or-override-merge-request-approval-rules). +- [At the instance level](../../../admin_area/merge_requests_approvals.md) + +If you don't define a [default approval rule](#add-an-approval-rule), +any user can approve a merge request. Even if you don't define a rule, you can still +enforce a [minimum number of required approvers](settings.md) in the project's settings. + +You can define a single rule to approve merge requests from among the available +rules, or you can select [multiple approval rules](#add-multiple-approval-rules). + +Merge requests that target a different project, such as from a fork to the upstream project, +use the default approval rules from the target (upstream) project, not the source (fork). + +## Add an approval rule + +To add a merge request approval rule: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**, and then select **Add approval rule**. +1. Add a human-readable **Rule name**. +1. Set the number of required approvals in **Approvals required**. A value of `0` makes + [the rule optional](#configure-optional-approval-rules), and any number greater than `0` + creates a required rule. +1. To add users or groups as approvers, search for users or groups that are + [eligible to approve](#eligible-approvers), and select **Add**. GitLab suggests approvers based on + previous authors of the files changed by the merge request. + + NOTE: + On GitLab.com, you can add a group as an approver if you're a member of that group or the + group is public. + +1. Select **Add approval rule**. + +Users of GitLab Premium and higher tiers can create [additional approval rules](#add-multiple-approval-rules). + +Your configuration for approval rule overrides determines if the new rule is applied +to existing merge requests: + +- If [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, + changes to these default rules are not applied to existing merge requests, except for + changes to the [target branch](#approvals-for-protected-branches) of the rule. +- If approval rule overrides are not allowed, all changes to default rules + are applied to existing merge requests. Any approval rules that were previously + manually [overridden](#edit-or-override-merge-request-approval-rules) during the + period when approval rule overrides where allowed, are not modified. + +## Edit an approval rule + +To edit a merge request approval rule: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**, and then select **Edit**. +1. (Optional) Change the **Rule name**. +1. Set the number of required approvals in **Approvals required**. The minimum value is `0`. +1. Add or remove eligible approvers, as needed: + - *To add users or groups as approvers,* search for users or groups that are + [eligible to approve](#eligible-approvers), and select **Add**. + + NOTE: + On GitLab.com, you can add a group as an approver if you're a member of that group or the + group is public. + + - *To remove users or groups,* identify the group or user to remove, and + select **{remove}** **Remove**. +1. Select **Update approval rule**. + +## Add multiple approval rules **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab Premium 11.10. + +In GitLab Premium and higher tiers, you can enforce multiple approval rules on a +merge request, and multiple default approval rules for a project. If your tier +supports multiple default rules: + +- When [adding](#add-an-approval-rule) or [editing](#edit-an-approval-rule) an approval rule + for a project, GitLab displays the **Add approval rule** button even after a rule is defined. +- When editing or overriding multiple approval rules + [on a merge request](#edit-or-override-merge-request-approval-rules), GitLab + displays the **Add approval rule** button even after a rule is defined. + +When an [eligible approver](#eligible-approvers) approves a merge request, it +reduces the number of approvals left (the **Approvals** column) for all rules that the approver belongs to: + + + +## Eligible approvers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. + +To be eligible as an approver for a project, a user must be a member of one or +more of these: + +- The project. +- The project's immediate parent [group](#group-approvers). +- A group that has access to the project via a [share](../../members/share_project_with_groups.md). +- A [group added as approvers](#group-approvers). + +The following users can approve merge requests if they have Developer or +higher [permissions](../../../permissions.md): + +- Users added as approvers at the project or merge request level. +- Users who are [Code owners](#code-owners-as-eligible-approvers) of the files + changed in the merge request. + +To show who has participated in the merge request review, the Approvals widget in +a merge request displays a **Commented by** column. This column lists eligible approvers +who commented on the merge request. It helps authors and reviewers identify who to +contact with questions about the merge request's content. + +If the number of required approvals is greater than the number of assigned approvers, +approvals from other users with Developer [permissions](../../../permissions.md) or higher +in the project counts toward meeting the required number of approvals, even if the +users were not explicitly listed in the approval rules. + +### Group approvers + +You can add a group of users as approvers, but those users count as approvers only if +they have direct membership to the group. In the future, group approvers may be +restricted to only groups [with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). + +A user's membership in an approvers group affects their individual ability to +approve in these ways: + +- A user already part of a group approver who is later added as an individual approver + counts as one approver, and not two. +- Merge request authors do not count as eligible approvers on their own merge requests by default. + To change this behavior, disable the + [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) + project setting. +- Committers to merge requests can approve a merge request. To change this behavior, enable the + [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work) + project setting. + +### Code owners as eligible approvers + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. +> - Moved to GitLab Premium in 13.9. + +If you add [code owners](../../code_owners.md) to your repository, the owners of files +become eligible approvers in the project. To enable this merge request approval rule: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Locate **Any eligible user** and select the number of approvals required: + +  + +You can also +[require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners) +for protected branches. **(PREMIUM)** + +## Merge request approval segregation of duties + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. +> - Moved to GitLab Premium in 13.9. + +You may need to grant users with [Reporter permissions](../../../permissions.md#project-members-permissions), +permission to approve merge requests before they can merge to a protected branch. +Some users (like managers) may not need permission to push or merge code, but still need +oversight on proposed work. To enable approval permissions for these users without +granting them push access: + +1. [Create a new group](../../../group/index.md#create-a-group). +1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), + and select the Reporter role for the user. +1. [Share the project with your group](../../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), + based on the Reporter role. +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select **Add approval rule** or **Update approval rule**. +1. [Add the group](../../../group/index.md#create-a-group) to the permission list. + +  + +### Edit or override merge request approval rules + +By default, the merge request author (or a user with sufficient [permissions](../../../permissions.md)) +can edit the approval rule listed in a merge request. When editing an approval rule +on a merge request, you can either add or remove approvers: + +1. In the merge request, find the **Approval rules section**. +1. When creating a new merge request, scroll to the **Approval Rules** section, + and add or remove your desired approval rules before selecting **Create merge request**. +1. When viewing an existing merge request: + 1. Select **Edit**. + 1. Scroll to the **Approval Rules** section. + 1. Add or remove your desired approval rules. + 1. Select **Save changes**. + +Administrators can change the [merge request approvals settings](settings.md#prevent-overrides-of-default-approvals) +to prevent users from overriding approval rules for merge requests. + +## Configure optional approval rules + +Merge request approvals can be optional for projects where approvals are +appreciated, but not required. To make an approval rule optional: + +- When you [create or edit a rule](#edit-an-approval-rule), set **Approvals required** to `0`. +- Use the [Merge requests approvals API](../../../../api/merge_request_approvals.md#update-merge-request-level-rule) + to set the `approvals_required` attribute to `0`. + +## Approvals for protected branches **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab Premium 12.8. + +Approval rules are often relevant only to specific branches, like your +[default branch](../../repository/branches/default.md). To configure an +approval rule for certain branches: + +1. [Create an approval rule](#add-an-approval-rule). +1. Go to your project and select **Settings**. +1. Expand **Merge request (MR) approvals**. +1. Select a **Target branch**: + - To protect all branches, select **Any branch**. + - To select a specific branch, select it from the list: + +  +1. To enable this configuration, read + [Code Owner's approvals for protected branches](../../protected_branches.md#protected-branches-approval-by-code-owners). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md new file mode 100644 index 00000000000..8769f6a7470 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -0,0 +1,125 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +--- + +# Merge request approval settings + +You can configure the settings for [merge request approvals](index.md) to +ensure the approval rules meet your use case. You can also configure +[approval rules](rules.md), which define the number and type of users who must +approve work before it's merged. Merge request approval settings define how +those rules are applied as a merge request moves toward completion. + +## Edit merge request approval settings + +To view or edit merge request approval settings: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. + +In this section of general settings, you can configure the settings described +on this page. + +## Prevent overrides of default approvals + +By default, users can override the approval rules you [create for a project](rules.md) +on a per-merge request basis. If you don't want users to change approval rules +on merge requests, you can disable this setting: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Prevent users from modifying MR approval rules in merge requests** checkbox. +1. Select **Save changes**. + +TODO This change affects all open merge requests. + +## Reset approvals on push + +By default, an approval on a merge request remains in place, even if you add more changes +after the approval. If you want to remove all existing approvals on a merge request +when more changes are added to it: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Require new approvals when new commits are added to an MR** checkbox. +1. Select **Save changes**. + +Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) +However, approvals are reset if the target branch is changed. + +## Prevent authors from approving their own work **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. +> - Moved to GitLab Premium in 13.9. + +By default, the author of a merge request cannot approve it. To change this setting: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Clear the **Prevent MR approval by the author** checkbox. +1. Select **Save changes**. + +Authors can edit the approval rule in an individual merge request and override +this setting, unless you configure one of these options: + +- [Prevent overrides of default approvals](#prevent-overrides-of-default-approvals) at + the project level. +- *(Self-managed instances only)* Prevent overrides of default approvals + [at the instance level](../../../admin_area/merge_requests_approvals.md). When configured + at the instance level, you can't edit this setting at the project or individual + merge request levels. + +## Prevent committers from approving their own work **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. +> - Moved to GitLab Premium in 13.9. + +By default, users who commit to a merge request can still approve it. At both +the project level or [instance level](../../../admin_area/merge_requests_approvals.md) +you can prevent committers from approving merge requests that are partially +their own. To do this: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Prevent MR approvals from users who make commits to the MR** checkbox. + If this checkbox is cleared, an administrator has disabled it + [at the instance level](../../../admin_area/merge_requests_approvals.md), and + it can't be changed at the project level. +1. Select **Save changes**. + +Even with this configuration, [code owners](../../code_owners.md) who contribute +to a merge request can approve merge requests that affect files they own. + +To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), +read the official Git documentation for an explanation. + +## Require authentication for approvals + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. +> - Moved to GitLab Premium in 13.9. + +You can force potential approvers to first authenticate with a password. This +permission enables an electronic signature for approvals, such as the one defined by +[Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)): + +1. Enable password authentication for the web interface, as described in the + [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Require user password for approvals** checkbox. +1. Select **Save changes**. + +## Security approvals in merge requests **(ULTIMATE)** + +You can require that a member of your security team approves a merge request if a +merge request could introduce a vulnerability. To learn more, see +[Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). + +## Related links + +- [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) +- [Compliance Dashboard](../../../compliance/compliance_dashboard/index.md) +- [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 76913351283..b33919c7fbe 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -64,7 +64,7 @@ using Docker-in-Docker. 1. First, set up GitLab Runner with a [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). -1. Configure the default Browser Performance Testing CI job as follows in your `.gitlab-ci.yml` file: +1. Configure the default Browser Performance Testing CI/CD job as follows in your `.gitlab-ci.yml` file: ```yaml include: @@ -75,17 +75,19 @@ using Docker-in-Docker. URL: https://example.com ``` -NOTE: -For versions before 12.4, see the information for [older GitLab versions](#gitlab-versions-123-and-older). -If you are using a Kubernetes cluster, use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) -instead. +WARNING: +In GitLab 14.0 and later, the job [is scheduled to be renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) +from `performance` to `browser_performance`. -The above example creates a `performance` job in your CI/CD pipeline and runs -sitespeed.io against the webpage you defined in `URL` to gather key metrics. +The above example: -The example uses a CI/CD template that is included in all GitLab installations since -12.4, but it doesn't work with Kubernetes clusters. If you are using GitLab 12.3 -or older, you must [add the configuration manually](#gitlab-versions-123-and-older) +- Creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you + defined in `URL` to gather key metrics. +- Uses a template that doesn't work with Kubernetes clusters. If you are using a Kubernetes cluster, + use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) + instead. +- Uses a CI/CD template that is included in all GitLab installations since 12.4. If you are using + GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance) @@ -181,63 +183,62 @@ performance: URL: environment_url.txt ``` -### GitLab versions 12.3 and older +### GitLab versions 13.2 and earlier -Browser Performance Testing has gone through several changes since it's introduction. +Browser Performance Testing has gone through several changes since its introduction. In this section we detail these changes and how you can run the test based on your GitLab version: +- In 13.2 the feature was renamed from `Performance` to `Browser Performance` with additional + template CI/CD variables. - In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). -- In 13.2 the feature was renamed from `Performance` to `Browser Performance` with -additional template CI/CD variables. The job name in the template is still `performance` -for compatibility reasons, but may be renamed to match in a future iteration. - For 11.5 to 12.3 no template is available and the job has to be defined manually as follows: -```yaml -performance: - stage: performance - image: docker:git - variables: - URL: https://example.com - SITESPEED_VERSION: 14.1.0 - SITESPEED_OPTIONS: '' - services: - - docker:stable-dind - script: - - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - - mkdir sitespeed-results - - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:$SITESPEED_VERSION --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL $SITESPEED_OPTIONS - - mv sitespeed-results/data/performance.json performance.json - artifacts: - paths: - - performance.json - - sitespeed-results/ - reports: - performance: performance.json -``` + ```yaml + performance: + stage: performance + image: docker:git + variables: + URL: https://example.com + SITESPEED_VERSION: 14.1.0 + SITESPEED_OPTIONS: '' + services: + - docker:stable-dind + script: + - mkdir gitlab-exporter + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js + - mkdir sitespeed-results + - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:$SITESPEED_VERSION --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL $SITESPEED_OPTIONS + - mv sitespeed-results/data/performance.json performance.json + artifacts: + paths: + - performance.json + - sitespeed-results/ + reports: + performance: performance.json + ``` - For 11.4 and earlier the job should be defined as follows: -```yaml -performance: - stage: performance - image: docker:git - variables: - URL: https://example.com - services: - - docker:stable-dind - script: - - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - - mkdir sitespeed-results - - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL - - mv sitespeed-results/data/performance.json performance.json - artifacts: - paths: - - performance.json - - sitespeed-results/ -``` + ```yaml + performance: + stage: performance + image: docker:git + variables: + URL: https://example.com + services: + - docker:stable-dind + script: + - mkdir gitlab-exporter + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js + - mkdir sitespeed-results + - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL + - mv sitespeed-results/data/performance.json performance.json + artifacts: + paths: + - performance.json + - sitespeed-results/ + ``` Upgrading to the latest version and using the templates is recommended, to ensure you receive the latest updates, including updates to the sitespeed.io versions. diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md new file mode 100644 index 00000000000..adcf4518209 --- /dev/null +++ b/doc/user/project/merge_requests/changes.md @@ -0,0 +1,151 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: index, reference +--- + +# Changes tab in merge requests + +The **Changes** tab on a [merge request](index.md), below the main merge request details and next to the discussion tab, +shows the changes to files between branches or commits. This view of changes to a +file is also known as a **diff**. By default, the diff view compares the file in the +merge request branch and the file in the target branch. + +The diff view includes the following: + +- The file's name and path. +- The number of lines added and deleted. +- Buttons for the following options: + - Toggle comments for this file; useful for inline reviews. + - Edit the file in the merge request's branch. + - Show full file, in case you want to look at the changes in context with the rest of the file. + - View file at the current commit. + - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). +- The changed lines, with the specific changes highlighted. + + + +## Merge request diff file navigation + +When reviewing changes in the **Changes** tab, the diff can be navigated using +the file tree or file list. As you scroll through large diffs with many +changes, you can quickly jump to any changed file using the file tree or file +list. + + + +## Collapsed files in the Changes view + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. + +When you review changes in the **Changes** tab, files with a large number of changes are collapsed +to improve performance. When files are collapsed, a warning appears at the top of the changes. +Select **Expand file** on any file to view the changes for that file. + +## File-by-file diff navigation + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. + +For larger merge requests, consider reviewing one file at a time. To enable this feature: + +1. In the top-right corner, select your avatar. +1. Select **Preferences**. +1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Select **Save changes**. + +After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can select **Prev** and **Next** to view other changed files. + + + +In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change +this behavior, you can do so from your **User preferences** (as explained above) or directly in a +merge request: + +1. Go to the merge request's **Changes** tab. +1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. +1. Select or clear the checkbox **Show one file at a time** to change the setting accordingly. + +This change overrides the choice you made in your user preferences and persists until you clear your +browser's cookies or change this behavior again. + +## Merge requests commit navigation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. + +To seamlessly navigate among commits in a merge request: + +1. Select the **Commits** tab. +1. Select a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Selecting **Prev** and **Next** buttons below the tab buttons. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. + + + +## Incrementally expand merge request diffs + +By default, the diff shows only the parts of a file which are changed. +To view more unchanged lines above or below a change select the +**Expand up** or **Expand down** icons. You can also select **Show unchanged lines** +to expand the entire file. + + + +In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a +merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the +entire content by selecting **Show file contents**. + +## Ignore whitespace changes in Merge Request diff view + +If you select the **Hide whitespace changes** button, you can see the diff +without whitespace changes (if there are any). This is also working when on a +specific commit page. + + + +NOTE: +You can append `?w=1` while on the diffs page of a merge request to ignore any +whitespace changes. + +## Mark files as viewed + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. +> - Deployed behind a feature flag, enabled by default. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** + +When reviewing a merge request with many files multiple times, it may be useful to the reviewer +to focus on new changes and ignore the files that they have already reviewed and don't want to +see anymore unless they are changed again. + +To mark a file as viewed: + +1. Go to the merge request's **Diffs** tab. +1. On the right-top of the file, locate the **Viewed** checkbox. +1. Select it to mark the file as viewed. + +Once checked, the file remains marked for that reviewer unless there are newly introduced +changes to its content or the checkbox is unchecked. + +### Enable or disable file views **(FREE SELF)** + +The file view feature is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to enable it for your instance. + +To enable it: + +```ruby +Feature.enable(:local_file_reviews) +``` + +To disable it: + +```ruby +Feature.disable(:local_file_reviews) +``` diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index f531cd52af1..eaeef12444e 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -16,7 +16,7 @@ with a **Cherry-pick** button in merge requests and commit details. After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request. - + After you click that button, a modal displays a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) @@ -32,7 +32,7 @@ where you can choose to either: When you cherry-pick a merge commit, GitLab displays a system note to the related merge request thread. It crosslinks the new commit and the existing merge request. - + Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 0fe1b9801cc..284d66dd591 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -53,20 +53,21 @@ See also the Code Climate list of [Supported Languages for Maintainability](http > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, an indicator is displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view. For example:  -To enable this feature, a GitLab administrator can run the following in a +To disable this feature, a GitLab administrator can run the following in a [Rails console](../../../administration/operations/rails_console.md): ```ruby # For the instance -Feature.enable(:codequality_mr_diff) +Feature.disable(:codequality_mr_diff) # For a single project -Feature.enable(:codequality_mr_diff, Project.find(<project id>)) +Feature.disable(:codequality_mr_diff, Project.find(<project id>)) ``` ## Use cases @@ -519,7 +520,7 @@ to change the default configuration, **not** a `.codequality.yml` file. If you u the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) is still used. -### No Code Quality report is displayed in a Merge Request +### No Code Quality report is displayed in a merge request This can be due to multiple reasons: @@ -531,7 +532,7 @@ This can be due to multiple reasons: nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. -- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the Merge Request widget to have no base report for comparison. +- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the merge request widget to have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. - Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 3a5a581198b..ce1dac0a96b 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -3,14 +3,14 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto -description: "How to create Merge Requests in GitLab." +description: "How to create merge requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- # How to create a merge request **(FREE)** Before creating a merge request, read through an -[introduction to Merge Requests](getting_started.md) +[introduction to merge requests](getting_started.md) to familiarize yourself with the concept, the terminology, and to learn what you can do with them. @@ -21,16 +21,16 @@ or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through- This document describes the several ways to create a merge request. When you start a new merge request, regardless of the method, -you are taken to the [**New Merge Request** page](#new-merge-request-page) +you are taken to the [**New merge request** page](#new-merge-request-page) to fill it with information about the merge request. If you push a new branch to GitLab, also regardless of the method, -you can click the [**Create Merge Request**](#create-merge-request-button) +you can click the [**Create merge request**](#create-merge-request-button) button and start a merge request from there. -## New Merge Request page +## New merge request page -On the **New Merge Request** page, start by filling in the title and description +On the **New merge request** page, start by filling in the title and description for the merge request. If commits already exist on the branch, GitLab suggests a merge request title for you: @@ -43,31 +43,31 @@ merge request title for you: The title is the only field that is mandatory in all cases. From there, you can fill it with information (title, description, -assignee(s), milestone, labels, approvers) and click **Create Merge Request**. +assignee(s), milestone, labels, approvers) and click **Create merge request**. From that initial screen, you can also see all the commits, pipelines, and file changes pushed to your branch before submitting the merge request. - + NOTE: You can push one or more times to your branch in GitLab before creating the merge request. -## Create Merge Request button +## Create merge request button Once you have pushed a new branch to GitLab, visit your repository in GitLab and to see a call-to-action at the top of your screen -from which you can click the button **Create Merge Request**. +from which you can click the button **Create merge request**. - + You can also see the **Create merge request** button in the top-right of the: - **Project** page. - **Repository > Files** page. -- **Merge Requests** page. +- **Merge requests** page. In this case, GitLab uses the most recent branch you pushed changes to as the source branch, and the default branch in the current @@ -90,7 +90,7 @@ Once you have added, edited, or uploaded the file: 1. Click **Commit changes**. If you chose to start a merge request, you are taken to the -[**New Merge Request** page](#new-merge-request-page), from +[**New merge request** page](#new-merge-request-page), from which you can fill it in with information and submit the merge request. The merge request targets the default branch of the repository. @@ -103,8 +103,8 @@ navigate to your project's **Repository > Branches** and click **New branch**. A new branch is created and you can start editing files. -Once committed and pushed, you can click on the [**Create Merge Request**](#create-merge-request-button) -button to open the [**New Merge Request** page](#new-merge-request-page). +Once committed and pushed, you can click on the [**Create merge request**](#create-merge-request-button) +button to open the [**New merge request** page](#new-merge-request-page). A new merge request is started using the current branch as the source, and the default branch in the current project as the target. @@ -140,7 +140,7 @@ remote: To create a merge request for docs-new-merge-request, visit: remote: https://gitlab-instance.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch ``` -Copy that link and paste it in your browser, and the [**New Merge Request page**](#new-merge-request-page) +Copy that link and paste it in your browser, and the [**New merge request page**](#new-merge-request-page) is displayed. There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI. @@ -148,20 +148,20 @@ There is also a number of [flags you can add to commands when pushing through th If you didn't push your branch to GitLab through the command line (for example, you used a Git CLI application to push your changes), you can create a merge request through the GitLab UI by clicking -the [**Create Merge Request**](#create-merge-request-button) button. +the [**Create merge request**](#create-merge-request-button) button. ## New merge request from an issue You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). -## New merge request from the Merge Requests page +## New merge request from the merge requests page You can start creating a new merge request by clicking the -**New merge request** button on the **Merge Requests** page in a project. +**New merge request** button on the **merge requests** page in a project. Then choose the source project and branch that contain your changes, and the target project and branch where you want to merge the changes into. Click on **Compare branches and continue** to go to the -[**New Merge Request** page](#new-merge-request-page) and fill in the details. +[**New merge request** page](#new-merge-request-page) and fill in the details. ## New merge request from a fork @@ -169,7 +169,7 @@ After forking a project and applying your local changes, complete the following create a merge request from your fork to contribute back to the main project: 1. Go to **Projects > Your Projects** and select your fork of the repository. -1. In the left menu, go to **Merge Requests**, and click **New Merge Request**. +1. In the left menu, go to **Merge requests**, and click **New merge request**. 1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch. 1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. You can set a [default target project](#set-the-default-target-project) to @@ -247,6 +247,6 @@ apply the patches. The target branch can be specified using the [`/target_branch` quick action](../quick_actions.md). If the source branch already exists, the patches are applied on top of it. -## Reviewing and managing Merge Requests +## Reviewing and managing merge requests -Once you have submitted a merge request, it can be [reviewed and managed](reviewing_and_managing_merge_requests.md) through GitLab. +Once you have submitted a merge request, it can be [reviewed and managed](reviews/index.md) through GitLab. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f973d9220f2..5556e54f875 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -4,13 +4,13 @@ group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Export Merge Requests to CSV **(FREE)** +# Export merge requests to CSV **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. -Exporting Merge Requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. +Exporting merge requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. -To export Merge Requests to CSV, navigate to your **Merge Requests** from the sidebar of a project and click **Export to CSV**. +To export merge requests to CSV, navigate to your **Merge requests** from the sidebar of a project and click **Export to CSV**. ## CSV Output diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index a030961e219..57850ad7304 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -66,7 +66,7 @@ when you mark a merge request as ready, notifications are triggered to When viewing or searching in your project's merge requests list, you can include or exclude draft merge requests: -1. In your project, select **Merge Requests** from the left sidebar. +1. Go to your project and select **Merge requests**. 1. In the navigation bar, click **Open**, **Merged**, **Closed**, or **All** to filter by merge request status. 1. Click the search box to display a list of filters and select **Draft**, or diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 80bdbce8d2c..68a63aebb90 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -42,14 +42,14 @@ This template requires: - A project built in Rails that uses RSpec for testing. - CI/CD configured to: - Use a Docker image with Ruby available. - - Use [Pipelines for Merge Requests](../../../ci/merge_request_pipelines/index.md#configuring-pipelines-for-merge-requests) + - Use [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md#configuring-pipelines-for-merge-requests) - [Pipelines for Merged Results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#enable-pipelines-for-merged-results) enabled in the project settings. - A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#overriding-external-template-values) this. ## Configuring Fast RSpec Failure -We'll use the following plain RSpec configuration as a starting point. It installs all the +We use the following plain RSpec configuration as a starting point. It installs all the project gems and executes `rspec`, on merge request pipelines only. ```yaml @@ -86,13 +86,13 @@ For illustrative purposes, let's say our Rails app spec suite consists of 100 sp If no Ruby files are changed: -- `rspec-rails-modified-paths-specs` will not run any tests. -- `rspec-complete` will run the full suite of 1000 tests. +- `rspec-rails-modified-paths-specs` does not run any tests. +- `rspec-complete` runs the full suite of 1000 tests. If one Ruby model is changed, for example `app/models/example.rb`, then `rspec-rails-modified-paths-specs` -will run the 100 tests for `example.rb`: +runs the 100 tests for `example.rb`: - If all of these 100 tests pass, then the full `rspec-complete` suite of 1000 tests is allowed to run. -- If any of these 100 tests fail, they will fail quickly, and `rspec-complete` will not run any tests. +- If any of these 100 tests fail, they fail quickly, and `rspec-complete` does not run any tests. The final case saves resources and time as the full 1000 test suite does not run. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 1bb333dcb14..459b8fa56ff 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -3,12 +3,12 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference -description: "Getting started with Merge Requests." +description: "Getting started with merge requests." --- -# Getting started with Merge Requests **(FREE)** +# Getting started with merge requests **(FREE)** -A Merge Request (**MR**) is the basis of GitLab as a code +A merge request (**MR**) is the basis of GitLab as a code collaboration and version control. When working in a Git-based platform, you can use branching @@ -25,7 +25,7 @@ avoiding changes to be pushed directly to the default branch without prior reviews, tests, and approvals. When you create a new feature branch, change the files, and push -it to GitLab, you have the option to create a **Merge Request**, +it to GitLab, you have the option to create a **merge request**, which is essentially a _request_ to merge one branch into another. The branch you added your changes into is called _source branch_ @@ -56,7 +56,7 @@ request's page at the top-right side: - [Assign](#assignee) the merge request to a colleague for review. With [multiple assignees](#multiple-assignees), you can assign it to more than one person at a time. - Set a [milestone](../milestones/index.md) to track time-sensitive changes. - Add [labels](../labels.md) to help contextualize and filter your merge requests over time. -- Require [approval](merge_request_approvals.md) from your team. **(PREMIUM)** +- [Require approval](approvals/index.md#required-approvals) from your team. **(PREMIUM)** - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. @@ -65,24 +65,24 @@ request's page at the top-right side: After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. -- [Perform inline code reviews](reviewing_and_managing_merge_requests.md#perform-inline-code-reviews). +- [Perform inline code reviews](reviews/index.md#perform-inline-code-reviews). - Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** -- Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets). -- Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps). +- Preview continuous integration [pipelines on the merge request widget](reviews/index.md#pipeline-status-in-merge-requests-widgets). +- Preview how your changes look directly on your deployed application with [Review Apps](reviews/index.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). -- Perform a [Review](../../discussions/index.md#merge-request-reviews) to create multiple comments on a diff and publish them when you're ready. -- Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. +- Perform a [Review](reviews/index.md) to create multiple comments on a diff and publish them when you're ready. +- Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. - Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). Many of these can be set when pushing changes from the command line, with [Git push options](../push_options.md). -See also other [features associated to merge requests](reviewing_and_managing_merge_requests.md#associated-features). +See also other [features associated to merge requests](reviews/index.md#associated-features). ### Assignee Choose an assignee to designate someone as the person responsible -for the first [review of the merge request](reviewing_and_managing_merge_requests.md). +for the first [review of the merge request](reviews/index.md). Open the drop down box to search for the user you wish to assign, and the merge request is added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). @@ -122,7 +122,7 @@ Requesting a code review is an important part of contributing code. However, dec your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. -The Merge Request Reviewers feature enables you to request a review of your work, and +The merge request Reviewers feature enables you to request a review of your work, and see the status of the review. Reviewers help distinguish the roles of the users involved in the merge request. In comparison to an **Assignee**, who is directly responsible for creating or merging a merge request, a **Reviewer** is a team member @@ -138,7 +138,7 @@ When selected, GitLab creates a [to-do list item](../../todos.md) for each revie > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. When editing the **Reviewers** field in a new or existing merge request, GitLab -displays the name of the matching [approval rule](merge_request_approvals.md#approval-rules) +displays the name of the matching [approval rule](approvals/rules.md) below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as `Codeowner` without group detail. This example shows reviewers and approval rules when creating a new merge request: @@ -234,7 +234,7 @@ The feature today works only on merge. Clicking the **Remove source branch** but after the merge request was merged will not automatically retarget a merge request. This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitlab/-/issues/321559). -## Recommendations and best practices for Merge Requests +## Recommendations and best practices for merge requests - When working locally in your branch, add multiple commits and only push when you're done, so GitLab runs only one pipeline for all the commits pushed diff --git a/doc/user/project/merge_requests/img/approve.png b/doc/user/project/merge_requests/img/approve.png Binary files differdeleted file mode 100644 index e2641f48c7a..00000000000 --- a/doc/user/project/merge_requests/img/approve.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/approve_additionally.png b/doc/user/project/merge_requests/img/approve_additionally.png Binary files differdeleted file mode 100644 index bab0cd4e041..00000000000 --- a/doc/user/project/merge_requests/img/approve_additionally.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/group_merge_requests_list_view.png b/doc/user/project/merge_requests/img/group_merge_requests_list_view.png Binary files differdeleted file mode 100644 index 7d0756505db..00000000000 --- a/doc/user/project/merge_requests/img/group_merge_requests_list_view.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/remove_approval.png b/doc/user/project/merge_requests/img/remove_approval.png Binary files differdeleted file mode 100644 index b178d26cf85..00000000000 --- a/doc/user/project/merge_requests/img/remove_approval.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 1fed30dc589..f587ab34d11 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -8,7 +8,6 @@ type: index, reference # Merge requests **(FREE)** Merge requests (MRs) are the way you check source code changes into a branch. - When you open a merge request, you can visualize and collaborate on the code changes before merge. Merge requests include: @@ -18,6 +17,11 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. +Merge requests contain tabs at the top of the page to help you navigate to +important parts of the merge request: **Overview**, **Commits**, **Pipelines**, and **Changes**. + + + To get started, read the [introduction to merge requests](getting_started.md). ## Merge request workflows @@ -29,10 +33,10 @@ For a software developer working in a team: 1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md). 1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD. 1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md). -1. You request the [approval](merge_request_approvals.md) from your manager. +1. You request the [approval](approvals/index.md) from your manager. 1. Your manager: 1. Pushes a commit with their final review. - 1. [Approves the merge request](merge_request_approvals.md). + 1. [Approves the merge request](approvals/index.md). 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md). 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD. 1. Your implementations were successfully shipped to your customer. @@ -43,35 +47,13 @@ For a web developer writing a webpage for your company's website: 1. You gather feedback from your reviewers. 1. You preview your changes with [Review Apps](../../../ci/review_apps/index.md). 1. You request your web designers for their implementation. -1. You request the [approval](merge_request_approvals.md) from your manager. +1. You request the [approval](approvals/index.md) from your manager. 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). 1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production. -## Merge request navigation tabs at the top - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33813) in GitLab 12.6. This positioning is experimental. - -In GitLab 12.5 and earlier, navigation tabs in merge requests (**Discussion**, -**Commits**, **Pipelines**, and **Changes**) were located after the merge request -widget. - -To facilitate navigation without scrolling, and based on user feedback, the tabs are -now located at the top of the merge request tab. A new **Overview** tab was added, -and next to **Overview** are **Commits**, **Pipelines**, and **Changes**. - - - -This change is behind a feature flag that is enabled by default. For -self-managed instances, it can be disabled through the Rails console by a GitLab -administrator with the following command: - -```ruby -Feature.disable(:mr_tabs_position) -``` - ## Related topics - [Create a merge request](creating_merge_requests.md) -- [Review and manage merge requests](reviewing_and_managing_merge_requests.md) +- [Review and manage merge requests](reviews/index.md) - [Authorization for merge requests](authorization_for_merge_requests.md) - [Testing and reports](testing_and_reports_in_merge_requests.md) diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 835350ade44..38d6ba062e4 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,416 +1,8 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, concepts +redirect_to: 'approvals/index.md' --- -# Merge Request Approvals **(FREE)** +This document was moved to [another location](approvals/index.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Free and higher tiers. -> - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. - -Code review is an essential practice of every successful project. Approving a -merge request is an important part of the review -process, as it clearly communicates the ability to merge the change. -A [merge request approvals API](../../../api/merge_request_approvals.md) is also available. - -## Optional Approvals - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. - -Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Free and higher tiers. -This provides a consistent mechanism for reviewers to approve merge requests, and ensures -maintainers know a change is ready to merge. Approvals in Free are optional, and do -not prevent a merge request from being merged when there is no approval. - -## External approvals **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -When you create an external approval rule, the following merge request actions sends information -about a merge request to a third party service: - -- Create -- Change -- Close - -This action enables use-cases such as: - -- Integration with 3rd party workflow tools, such as [ServiceNow](https://www.servicenow.co.uk/). -- Integration with custom tools designed to approve merge requests from outside of GitLab. - -You can find more information about use-cases, development timelines and the feature discovery in -the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). - -The intention for this feature is to allow those 3rd party tools to approve a merge request similarly to how users current do. - -NOTE: -The lack of an external approval does not block the merging of a merge request. - -You can modify external approval rules through the [REST API](../../../api/merge_request_approvals.md#external-project-level-mr-approvals). - -## Required Approvals **(PREMIUM)** - -> - [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. -> - Moved to GitLab Premium in 13.9. - -Required approvals enable enforced code review by requiring specified people -to approve a merge request before it can be merged. - -Required approvals enable multiple use cases: - -- Enforcing review of all code that gets merged into a repository. -- Specifying reviewers for a given proposed code change, as well as a minimum number - of reviewers, through [Approval rules](#approval-rules). -- Specifying categories of reviewers, such as backend, frontend, quality assurance, - database, and so on, for all proposed code changes. -- Designating [Code Owners as eligible approvers](#code-owners-as-eligible-approvers), - determined by the files changed in a merge request. -- [Requiring approval from a security team](#security-approvals-in-merge-requests) - before merging code that could introduce a vulnerability.**(ULTIMATE)** - -### Approval Rules - -Approval rules define how many approvals a merge request must receive before it can -be merged, and optionally which users should do the approving. Approvals can be defined: - -- [As project defaults](#adding--editing-a-default-approval-rule). -- [Per merge request](#editing--overriding-approval-rules-per-merge-request). - -If no approval rules are defined, any user can approve a merge request. However, the default -minimum number of required approvers can still be set in the -[settings for merge request approvals](#approval-settings). - -You can opt to define one single rule to approve a merge request among the available rules -or choose more than one with [multiple approval rules](#multiple-approval-rules). - -NOTE: -On GitLab.com, you can add a group as an approver if you're a member of that group or the -group is public. - -#### Eligible Approvers - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. - -The following users can approve merge requests: - -- Users who have been added as approvers at the project or merge request levels with - developer or higher [permissions](../../permissions.md). -- [Code owners](#code-owners-as-eligible-approvers) of the files changed by the merge request - that have developer or higher [permissions](../../permissions.md). - -An individual user can be added as an approver for a project if they are a member of: - -- The project. -- The project's immediate parent group. -- A group that has access to the project via a [share](../members/share_project_with_groups.md). - -A group of users can also be added as approvers, though they only count as approvers if -they have direct membership to the group. In the future, group approvers may be -[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). - -If a user is added as an individual approver and is also part of a group approver, -then that user is just counted once. The merge request author, and users who have committed -to the merge request, do not count as eligible approvers, -if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default) -and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) -are enabled on the project settings. - -When an eligible approver comments on a merge request, it displays in the -**Commented by** column of the Approvals widget. It indicates who participated in -the merge request review. Authors and reviewers can also identify who they should reach out -to if they have any questions about the content of the merge request. - -##### Implicit Approvers - -If the number of required approvals is greater than the number of assigned approvers, -approvals from other users counts towards meeting the requirement. These would be -users with developer [permissions](../../permissions.md) or higher in the project who -were not explicitly listed in the approval rules. - -##### Code Owners as eligible approvers - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. -> - Moved to GitLab Premium in 13.9. - -If you add [Code Owners](../code_owners.md) to your repository, the owners to the -corresponding files become eligible approvers, together with members with Developer -or higher [permissions](../../permissions.md). - -To enable this merge request approval rule: - -1. Navigate to your project's **Settings > General** and expand - **Merge request (MR) approvals**. -1. Locate **Any eligible user** and choose the number of approvals required. - - - -Once set, merge requests can only be merged once approved by the -number of approvals you've set. GitLab accepts approvals from -users with Developer or higher permissions, as well as by Code Owners, -indistinguishably. - -Alternatively, you can **require** -[Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** - -#### Merge Request approval segregation of duties - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. -> - Moved to Premium in 13.9. - -Managers or operators with [Reporter permissions](../../permissions.md#project-members-permissions) -to a project sometimes need to be required approvers of a merge request, -before a merge to a protected branch begins. These approvers aren't allowed -to push or merge code to any branches. - -To enable this access: - -1. [Create a new group](../../group/index.md#create-a-group), and then - [add the user to the group](../../group/index.md#add-users-to-a-group), - ensuring you select the Reporter role for the user. -1. [Share the project with your group](../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), - based on the Reporter role. -1. Navigate to your project's **Settings > General**, and in the - **Merge request (MR) approvals** section, click **Expand**. -1. Select **Add approval rule** or **Update approval rule**. -1. [Add the group](../../group/index.md#create-a-group) to the permission list. - - - -#### Adding / editing a default approval rule - -To add or edit the default merge request approval rule: - -1. Navigate to your project's **Settings > General** and expand **Merge request (MR) approvals**. - -1. Click **Add approval rule**, or **Edit**. - - Add or change the **Rule name**. - - Set the number of required approvals in **Approvals required**. The minimum value is `0`. - - (Optional) Search for users or groups that are [eligible to approve](#eligible-approvers) - merge requests and click the **Add** button to add them as approvers. Before typing - in the search field, approvers are suggested based on the previous authors of - the files being changed by the merge request. - - (Optional) Click the **{remove}** **Remove** button next to a group or user to delete it from - the rule. -1. Click **Add approval rule** or **Update approval rule**. - -When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to these default rules are not applied to existing merge -requests, except for changes to the [target branch](#scoped-to-protected-branch) of -the rule. - -When approval rule overrides are not allowed, all changes to these default rules -are applied to existing merge requests. Any approval rules that had previously been -manually [overridden](#editing--overriding-approval-rules-per-merge-request) during a -period when approval rule overrides where allowed, are not modified. - -NOTE: -If a merge request targets a different project, such as from a fork to the upstream project, -the default approval rules are taken from the target (upstream) project, not the -source (fork). - -##### Editing / overriding approval rules per merge request - -> Introduced in GitLab Enterprise Edition 9.4. - -By default, the merge request approval rule listed in each merge request (MR) can be -edited by the MR author or a user with sufficient [permissions](../../permissions.md). -This ability can be disabled in the [merge request approvals settings](#prevent-overriding-default-approvals). - -One possible scenario would be to add more approvers than were defined in the default -settings. - -When creating or editing a merge request, find the **Approval rules** section, then follow -the same steps as [Adding / editing a default approval rule](#adding--editing-a-default-approval-rule). - -#### Set up an optional approval rule - -MR approvals can be configured to be optional, which can help if you're working -on a team where approvals are appreciated, but not required. - -To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. - -You can also set an optional approval rule through the [Merge requests approvals API](../../../api/merge_request_approvals.md#update-merge-request-level-rule), by setting the `approvals_required` attribute to `0`. - -#### Multiple approval rules **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. - -In GitLab Premium, it is possible to have multiple approval rules per merge request, -as well as multiple default approval rules per project. - -Adding or editing multiple default rules is identical to -[adding or editing a single default approval rule](#adding--editing-a-default-approval-rule), -except the **Add approval rule** button is available to add more rules, even after -a rule is already defined. - -Similarly, editing or overriding multiple approval rules per merge request is identical -to [editing or overriding approval rules per merge request](#editing--overriding-approval-rules-per-merge-request), -except the **Add approval rule** button is available to add more rules, even after -a rule is already defined. - -When an [eligible approver](#eligible-approvers) approves a merge request, it -reduces the number of approvals left for all rules that the approver belongs to. - - - -#### Scoped to protected branch **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. - -Approval rules are often only relevant to specific branches, like `master`. -When configuring [**Default Approval Rules**](#adding--editing-a-default-approval-rule) -these can be scoped to all the protected branches at once by navigating to your project's -**Settings**, expanding **Merge request (MR) approvals**, and selecting **Any branch** from -the **Target branch** dropdown. - -Alternatively, you can select a very specific protected branch from the **Target branch** dropdown: - - - -To enable this configuration, see [Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). - -### Adding or removing an approval - -When an [eligible approver](#eligible-approvers) visits an open merge request, -one of the following is possible: - -- If the required number of approvals has _not_ been yet met, they can approve - it by clicking the displayed **Approve** button. - -  - -- If the required number of approvals has already been met, they can still - approve it by clicking the displayed **Approve additionally** button. - -  - -- **They have already approved this merge request**: They can remove their approval. - -  - -When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to default approval rules will **not** be applied to existing -merge requests, except for changes to the [target branch](#scoped-to-protected-branch) -of the rule. - -NOTE: -The merge request author is not allowed to approve their own merge request if -[**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) -is enabled in the project settings. - -After the approval rules have been met, the merge request can be merged if there is nothing -else blocking it. Note that the merge request could still be blocked by other conditions, -such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), -or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). - -### Approval settings - -The settings for Merge Request Approvals are found by going to -**Settings > General** and expanding **Merge request (MR) approvals**. - -#### Prevent overriding default approvals - -Regardless of the approval rules you choose for your project, users can edit them in every merge -request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). -To prevent that from happening: - -1. Select the **Prevent users from modifying MR approval rules in merge requests.** checkbox. -1. Click **Save changes**. - -#### Resetting approvals on push - -You can force all approvals on a merge request to be removed when new commits are -pushed to the source branch of the merge request. If disabled, approvals persist -even if there are changes added to the merge request. To enable this feature: - -1. Check the **Require new approvals when new commits are added to an MR.** - checkbox. -1. Click **Save changes**. - -NOTE: -Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) -from the UI. However, approvals are reset if the target branch is changed. - -#### Allowing merge request authors to approve their own merge requests **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. -> - Moved to GitLab Premium in 13.9. - -By default, projects are configured to prevent merge requests from being approved by -their own authors. To change this setting: - -1. Go to your project's **Settings > General**, expand **Merge request (MR) approvals**. -1. Uncheck the **Prevent MR approval by the author.** checkbox. -1. Click **Save changes**. - -Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). - -You can prevent authors from approving their own merge requests -[at the instance level](../../admin_area/merge_requests_approvals.md). When enabled, -this setting is disabled on the project level, and not editable. - -#### Prevent approval of merge requests by their committers **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. -> - Moved to GitLab Premium in 13.9. - -You can prevent users who have committed to a merge request from approving it, -though code authors can still approve. You can enable this feature -[at the instance level](../../admin_area/merge_requests_approvals.md), which -disables changes to this feature at the project level. If you prefer to manage -this feature at the project level, you can: - -1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox. - If this check box is disabled, this feature has been disabled - [at the instance level](../../admin_area/merge_requests_approvals.md). -1. Click **Save changes**. - -Read the official Git documentation for an explanation of the -[differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). - -#### Require authentication when approving a merge request - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. -> - Moved to GitLab Premium in 13.9. - -NOTE: -To require authentication when approving a merge request, you must enable -**Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -in the Admin Area. - -You can force the approver to enter a password in order to authenticate before adding -the approval. This enables an Electronic Signature for approvals such as the one defined -by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)). -To enable this feature: - -1. Check the **Require user password for approvals.** checkbox. -1. Click **Save changes**. - -### Security approvals in merge requests **(ULTIMATE)** - -Merge Request Approvals can be configured to require approval from a member -of your security team when a vulnerability would be introduced by a merge request. - -For more information, see -[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests). - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +<!-- This redirect file can be deleted after <2021-07-27>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index fc5cc4d958b..4534ce194bf 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge Request dependencies **(PREMIUM)** +# Merge request dependencies **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge Requests dependencies" in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge request dependencies" in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. > - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. Merge request dependencies allows a required order of merging diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 58f2c310375..b1da336aae9 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -67,7 +67,7 @@ You should be careful to configure CI/CD so that pipelines run for every merge r ### Limitations When this setting is enabled, a merge request is prevented from being merged if there -is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#onlyexcept-advanced) +is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#only--except) or [`rules`](../../../ci/yaml/README.md#rules) are used and they don't generate any pipelines. You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index aba75403a2a..0475996cb9b 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -1,452 +1,8 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: index, reference +redirect_to: 'reviews/index.md' --- -# Reviewing and managing merge requests **(FREE)** +This document was moved to [another location](reviews/index.md). -Merge requests are the primary method of making changes to files in a GitLab project. -Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md), -which is then reviewed, and accepted (or rejected). - -## View project merge requests - -View all the merge requests in a project by navigating to **Project > Merge Requests**. - -When you access your project's merge requests, GitLab displays them in a list. -Use the tabs to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). - - - -## View merge requests for all projects in a group - -View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs. - -You can [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists) from here. - - - -## Cached merge request count - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -In a group, the sidebar displays the total count of open merge requests and this value is cached if higher -than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. - -### Enable or disable cached merge request count **(FREE SELF)** - -Cached merge request count in the left sidebar is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:cached_sidebar_merge_requests_count) -``` - -To enable it: - -```ruby -Feature.enable(:cached_sidebar_merge_requests_count) -``` - -## Semi-linear history merge requests - -A merge commit is created for every merge, but the branch is only merged if -a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build also succeeds after the merge. - -Navigate to a project's settings, select the **Merge commit with semi-linear history** -option under **Merge Requests: Merge method** and save your changes. - -## View changes between file versions - -The **Changes** tab, below the main merge request details and next to the discussion tab, -shows the changes to files between branches or commits. This view of changes to a -file is also known as a **diff**. By default, the diff view compares the file in the -merge request branch and the file in the target branch. - -The diff view includes the following: - -- The file's name and path. -- The number of lines added and deleted. -- Buttons for the following options: - - Toggle comments for this file; useful for inline reviews. - - Edit the file in the merge request's branch. - - Show full file, in case you want to look at the changes in context with the rest of the file. - - View file at the current commit. - - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). -- The changed lines, with the specific changes highlighted. - - - -### Merge request diff file navigation - -When reviewing changes in the **Changes** tab the diff can be navigated using -the file tree or file list. As you scroll through large diffs with many -changes, you can quickly jump to any changed file using the file tree or file -list. - - - -### Collapsed files in the Changes view - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. - -When you review changes in the **Changes** tab, files with a large number of changes are collapsed -to improve performance. When files are collapsed, a warning appears at the top of the changes. -Click **Expand file** on any file to view the changes for that file. - -### File-by-file diff navigation - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. - -For larger merge requests, consider reviewing one file at a time. To enable this feature: - -1. In the top-right corner, select your avatar. -1. Select **Preferences**. -1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. -1. Select **Save changes**. - -After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can click **Prev** and **Next** to view other changed files. - - - -In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change -this behavior, you can do so from your **User preferences** (as explained above) or directly in a -merge request: - -1. Go to the merge request's **Changes** tab. -1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. -1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly. - -This change overrides the choice you made in your user preferences and persists until you clear your -browser's cookies or change this behavior again. - -### Merge requests commit navigation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. - -To seamlessly navigate among commits in a merge request: - -1. Select the **Commits** tab. -1. Select a commit to open it in the single-commit view. -1. Navigate through the commits by either: - - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. - - - -### Incrementally expand merge request diffs - -By default, the diff shows only the parts of a file which are changed. -To view more unchanged lines above or below a change click on the -**Expand up** or **Expand down** icons. You can also click on **Show unchanged lines** -to expand the entire file. - - - -In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a -merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the -entire content by clicking **Show file contents**. - -### Ignore whitespace changes in Merge Request diff view - -If you click the **Hide whitespace changes** button, you can see the diff -without whitespace changes (if there are any). This is also working when on a -specific commit page. - - - -NOTE: -You can append `?w=1` while on the diffs page of a merge request to ignore any -whitespace changes. - -## Mark files as viewed - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** - -When reviewing a merge request with many files multiple times, it may be useful to the reviewer -to focus on new changes and ignore the files that they have already reviewed and don't want to -see anymore unless they are changed again. - -To mark a file as viewed: - -1. Go to the merge request's **Diffs** tab. -1. On the right-top of the file, locate the **Viewed** checkbox. -1. Check it to mark the file as viewed. - -Once checked, the file remains marked for that reviewer unless there are newly introduced -changes to its content or the checkbox is unchecked. - -### Enable or disable file views **(FREE SELF)** - -The file view feature is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to enable it for your instance. - -To enable it: - -```ruby -Feature.enable(:local_file_reviews) -``` - -To disable it: - -```ruby -Feature.disable(:local_file_reviews) -``` - -## Perform inline code reviews - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. - -In a merge request, you can leave comments in any part of the file being changed. -In the Merge Request Diff UI, you can: - -- **Comment on a single line**: Click the **{comment}** **comment** icon in the - gutter to expand the diff lines and display a comment box. -- [**Comment on multiple lines**](#commenting-on-multiple-lines). - -### Commenting on multiple lines - -> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. - -When commenting on a diff, you can select which lines of code your comment refers -to by either: - - - -- Clicking and dragging the **{comment}** **comment** icon in the gutter to highlight - lines in the diff. GitLab expands the diff lines and displays a comment box. -- After starting a comment by clicking the **{comment}** **comment** icon in the - gutter, select the first line number your comment refers to in the **Commenting on lines** - select box. New comments default to single-line comments, unless you select - a different starting line. - -Multiline comments display the comment's line numbers above the body of the comment: - - - -## Pipeline status in merge requests widgets - -If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, -you can see: - -- Both pre-merge and post-merge pipelines and the environment information if any. -- Which deployments are in progress. - -If an application is successfully deployed to an -[environment](../../../ci/environments/index.md), the deployed environment and the link to the -Review App are both shown. - -NOTE: -When the pipeline fails in a merge request but it can still be merged, -the **Merge** button is colored red. - -### Post-merge pipeline status - -When a merge request is merged, you can see the post-merge pipeline status of -the branch the merge request was merged into. For example, when a merge request -is merged into the [default branch](../repository/branches/default.md) and then triggers a deployment to the staging -environment. - -Ongoing deployments are shown, and the state (deploying or deployed) -for environments. If it's the first time the branch is deployed, the link -returns a `404` error until done. During the deployment, the stop button is -disabled. If the pipeline fails to deploy, the deployment information is hidden. - - - -For more information, [read about pipelines](../../../ci/pipelines/index.md). - -### Merge when pipeline succeeds (MWPS) - -Set a merge request that looks ready to merge to -[merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). - -### Live preview with Review Apps - -If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, -you can preview the changes submitted to a feature branch through a merge request -on a per-branch basis. You don't need to checkout the branch, install, and preview locally. -All your changes are available to preview by anyone with the Review Apps link. - -With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the -merge request widget takes you directly to the pages changed, making it easier and -faster to preview proposed modifications. - -[Read more about Review Apps](../../../ci/review_apps/index.md). - -## Associated features - -These features are associated with merge requests: - -- [Bulk editing merge requests](../../project/bulk_editing.md): - Update the attributes of multiple merge requests simultaneously. -- [Cherry-pick changes](cherry_pick_changes.md): - Cherry-pick any commit in the UI by clicking the **Cherry-pick** button in a merged merge requests or a commit. -- [Fast-forward merge requests](fast_forward_merge.md): - For a linear Git history and a way to accept merge requests without creating merge commits -- [Find the merge request that introduced a change](versions.md): - When viewing the commit details page, GitLab links to the merge request(s) containing that commit. -- [Merge requests versions](versions.md): - Select and compare the different versions of merge request diffs -- [Resolve conflicts](resolve_conflicts.md): - GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. -- [Revert changes](revert_changes.md): - Revert changes from any commit from a merge request. - -## Troubleshooting - -Sometimes things don't go as expected in a merge request. Here are some -troubleshooting steps. - -### Merge request cannot retrieve the pipeline status - -This can occur if Sidekiq doesn't pick up the changes fast enough. - -#### Sidekiq - -Sidekiq didn't process the CI state change fast enough. Please wait a few -seconds and the status should update automatically. - -#### Bug - -Merge Request pipeline statuses can't be retrieved when the following occurs: - -1. A Merge Request is created -1. The Merge Request is closed -1. Changes are made in the project -1. The Merge Request is reopened - -To enable the pipeline status to be properly retrieved, close and reopen the -Merge Request again. - -## Tips - -Here are some tips to help you be more efficient with merge requests in -the command line. - -### Copy the branch name for local checkout - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. - -The merge request sidebar contains the branch reference for the source branch -used to contribute changes for this merge request. - -To copy the branch reference into your clipboard, click the **Copy branch name** button -(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally -via command line by running `git checkout <branch-name>`. - -### Checkout merge requests locally through the `head` ref - -A merge request contains all the history from a repository, plus the additional -commits added to the branch associated with the merge request. Here's a few -ways to checkout a merge request locally. - -You can checkout a merge request locally even if the source -project is a fork (even a private fork) of the target project. - -This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) -that is available for each merge request. It allows checking out a merge -request via its ID instead of its branch. - -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab -13.4, 14 days after a merge request gets closed or merged, the merge request -`head` ref is deleted. This means that the merge request is not available -for local checkout via the merge request `head` ref anymore. The merge request -can still be re-opened. If the merge request's branch -exists, you can still check out the branch, as it isn't affected. - -#### Checkout locally by adding a Git alias - -Add the following alias to your `~/.gitconfig`: - -```plaintext -[alias] - mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - -``` - -Now you can check out a particular merge request from any repository and any -remote. For example, to check out the merge request with ID 5 as shown in GitLab -from the `origin` remote, do: - -```shell -git mr origin 5 -``` - -This fetches the merge request into a local `mr-origin-5` branch and check -it out. - -#### Checkout locally by modifying `.git/config` for a given repository - -Locate the section for your GitLab remote in the `.git/config` file. It looks -like this: - -```plaintext -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* -``` - -You can open the file with: - -```shell -git config -e -``` - -Now add the following line to the above section: - -```plaintext -fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -In the end, it should look like this: - -```plaintext -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* - fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -Now you can fetch all the merge requests: - -```shell -git fetch origin - -... -From https://gitlab.com/gitlab-org/gitlab-foss.git - * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 - * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 -... -``` - -And to check out a particular merge request: - -```shell -git checkout origin/merge-requests/1 -``` - -All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. +<!-- This redirect file can be deleted after <2021-08-03>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..e8aa4b7c730 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..d15f5d53e55 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..3e1e9c20af9 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..e27fa629672 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png b/doc/user/project/merge_requests/reviews/img/comment-on-any-diff-line_v13_10.png Binary files differindex a31fea85be9..a31fea85be9 100644 --- a/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png +++ b/doc/user/project/merge_requests/reviews/img/comment-on-any-diff-line_v13_10.png diff --git a/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png Binary files differnew file mode 100644 index 00000000000..170c04542dd --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png diff --git a/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..92d5ba5ddda --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png diff --git a/doc/user/project/merge_requests/img/merge_request_pipeline.png b/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png Binary files differindex ce1d6bab536..ce1d6bab536 100644 --- a/doc/user/project/merge_requests/img/merge_request_pipeline.png +++ b/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png Binary files differnew file mode 100644 index 00000000000..6b4899bf67f --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png Binary files differnew file mode 100644 index 00000000000..ced33682459 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png Binary files differnew file mode 100644 index 00000000000..2f0be3b6d06 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_start.png b/doc/user/project/merge_requests/reviews/img/mr_review_start.png Binary files differnew file mode 100644 index 00000000000..08b4c6bb82b --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_start.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png Binary files differnew file mode 100644 index 00000000000..4bef38f7808 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png Binary files differnew file mode 100644 index 00000000000..476c50b9098 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png Binary files differnew file mode 100644 index 00000000000..80424d1f056 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png diff --git a/doc/user/project/merge_requests/img/multiline-comment-saved.png b/doc/user/project/merge_requests/reviews/img/multiline-comment-saved.png Binary files differindex cceab36e62b..cceab36e62b 100644 --- a/doc/user/project/merge_requests/img/multiline-comment-saved.png +++ b/doc/user/project/merge_requests/reviews/img/multiline-comment-saved.png diff --git a/doc/user/project/merge_requests/reviews/img/pending_review_comment.png b/doc/user/project/merge_requests/reviews/img/pending_review_comment.png Binary files differnew file mode 100644 index 00000000000..70a66b3f4f0 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/pending_review_comment.png diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png Binary files differindex 625d47b1142..625d47b1142 100644 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png +++ b/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..fa8331effdb --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png Binary files differnew file mode 100644 index 00000000000..58e0508d8cf --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png Binary files differnew file mode 100644 index 00000000000..927b4f812a5 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png Binary files differnew file mode 100644 index 00000000000..6f29107146d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..a4c9df0ebb9 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md new file mode 100644 index 00000000000..e98a230c0de --- /dev/null +++ b/doc/user/project/merge_requests/reviews/index.md @@ -0,0 +1,417 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: index, reference +--- + +# Review and manage merge requests **(FREE)** + +[Merge requests](../index.md) are the primary method of making changes to files in a +GitLab project. [Create and submit a merge request](../creating_merge_requests.md) +to propose changes. Your team makes [suggestions](suggestions.md) and leaves +[comments](../../../discussions/index.md). When your work is reviewed, your team +members can choose to accept or reject it. + +## View merge requests + +You can view merge requests for a specific project, or for all projects in a group: + +- **Specific project**: Go to your project and select **Merge requests**. +- **All projects in a group**: Go to your group and select **Merge requests**. + If your group contains subgroups, this view also displays merge requests from the subgroup projects. + GitLab displays a count of open merge requests in the left sidebar, but + [caches the value](#cached-merge-request-count) for groups with a large number of + open merge requests. + +GitLab displays open merge requests, with tabs to filter the list by open and closed status: + + + +You can [search and filter](../../../search/index.md#filtering-issue-and-merge-request-lists), +the results, or select a merge request to begin a review. + +## Bulk edit merge requests at the project level + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a project, you can edit the following attributes: + +- Status (open/closed) +- Assignee +- Milestone +- Labels +- Subscriptions + +To update multiple project merge requests at the same time: + +1. In a project, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit merge requests at the group level + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a group, you can edit the following attributes: + +- Milestone +- Labels + +To update multiple group merge requests at the same time: + +1. In a group, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Review a merge request + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. + +When you review a merge request, you can create comments that are visible only +to you. When you're ready, you can publish them together in a single action. +To start your review: + +1. Go to the merge request you want to review, and select the **Changes** tab. + To learn more about navigating the diffs displayed in this tab, read + [Changes tab in merge requests](../changes.md). +1. Select a line of code. In GitLab version 13.2 and later, you can [highlight a set of lines](#comment-on-multiple-lines). +1. Write your first comment, and select **Start a review** below your comment: +  +1. Continue adding comments to lines of code, and select the appropriate button after + you write a comment: + - **Add to review**: Keep this comment private and add to the current review. + These review comments are marked **Pending** and are visible only to you. + - **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. +1. (Optional) You can use [quick actions](../../quick_actions.md) inside review comments. + The comment shows the actions to perform after publication, but does not perform them + until you submit your review. +1. When your review is complete, you can [submit the review](#submit-a-review). Your comments + are now visible, and any quick actions included your comments are performed. + +### Submit a review + +You can submit your completed review in multiple ways: + +- Use the `/submit_review` [quick action](../../quick_actions.md) in the text of a non-review comment. +- When creating a review comment, select **Submit review**. +- Scroll to the bottom of the screen and select **Submit review**. + +When you submit your review, GitLab: + +- Publishes the comments in your review. +- Sends a single email to every notifiable user of the merge request, with your + review comments attached. Replying to this email creates a new comment on the merge request. +- Perform any quick actions you added to your review comments. + +### Resolving/Unresolving threads + +Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolvable-comments-and-threads). +When replying to a comment, a checkbox is displayed to resolve or unresolve +the thread after publication. + + + +If a particular pending comment resolves or unresolves the thread, this is shown on the pending +comment itself. + + + + + +### Adding a new comment + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. + +If you have a review in progress, you will be presented with the option to **Add to review**: + + + +## Semi-linear history merge requests + +A merge commit is created for every merge, but the branch is only merged if +a fast-forward merge is possible. This ensures that if the merge request build +succeeded, the target branch build also succeeds after the merge. + +1. Go to your project and select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Merge method** section, select **Merge commit with semi-linear history**. +1. Select **Save changes**. + +## Perform inline code reviews + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. + +In a merge request, you can leave comments in any part of the file being changed. +In the merge request Diff UI, you can: + +- **Comment on a single line**: Select the **{comment}** **comment** icon in the + gutter to expand the diff lines and display a comment box. +- [**Comment on multiple lines**](#comment-on-multiple-lines). + +### Comment on multiple lines + +> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. + +When commenting on a diff, you can select which lines of code your comment refers +to by either: + + + +- Dragging the **{comment}** **comment** icon in the gutter to highlight + lines in the diff. GitLab expands the diff lines and displays a comment box. +- After starting a comment by selecting the **{comment}** **comment** icon in the + gutter, select the first line number your comment refers to in the **Commenting on lines** + select box. New comments default to single-line comments, unless you select + a different starting line. + +Multiline comments display the comment's line numbers above the body of the comment: + + + +## Pipeline status in merge requests widgets + +If you've set up [GitLab CI/CD](../../../../ci/README.md) in your project, +you can see: + +- Both pre-merge and post-merge pipelines and the environment information if any. +- Which deployments are in progress. + +If an application is successfully deployed to an +[environment](../../../../ci/environments/index.md), the deployed environment and the link to the +Review App are both shown. + +NOTE: +When the pipeline fails in a merge request but it can still be merged, +the **Merge** button is colored red. + +### Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the [default branch](../../repository/branches/default.md) and then triggers a deployment to the staging +environment. + +Ongoing deployments are shown, and the state (deploying or deployed) +for environments. If it's the first time the branch is deployed, the link +returns a `404` error until done. During the deployment, the stop button is +disabled. If the pipeline fails to deploy, the deployment information is hidden. + + + +For more information, [read about pipelines](../../../../ci/pipelines/index.md). + +### Merge when pipeline succeeds (MWPS) + +Set a merge request that looks ready to merge to +[merge automatically when CI pipeline succeeds](../merge_when_pipeline_succeeds.md). + +### Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, +you can preview the changes submitted to a feature branch through a merge request +on a per-branch basis. You don't need to checkout the branch, install, and preview locally. +All your changes are available to preview by anyone with the Review Apps link. + +With GitLab [Route Maps](../../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../../ci/review_apps/index.md). + +## Associated features + +These features are associated with merge requests: + +- [Bulk editing merge requests](../../../project/bulk_editing.md): + Update the attributes of multiple merge requests simultaneously. +- [Cherry-pick changes](../cherry_pick_changes.md): + Cherry-pick any commit in the UI by selecting the **Cherry-pick** button in a merged merge requests or a commit. +- [Fast-forward merge requests](../fast_forward_merge.md): + For a linear Git history and a way to accept merge requests without creating merge commits +- [Find the merge request that introduced a change](../versions.md): + When viewing the commit details page, GitLab links to the merge request(s) containing that commit. +- [Merge requests versions](../versions.md): + Select and compare the different versions of merge request diffs +- [Resolve conflicts](../resolve_conflicts.md): + GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. +- [Revert changes](../revert_changes.md): + Revert changes from any commit from a merge request. + +## Troubleshooting + +Sometimes things don't go as expected in a merge request. Here are some +troubleshooting steps. + +### Merge request cannot retrieve the pipeline status + +This can occur if Sidekiq doesn't pick up the changes fast enough. + +#### Sidekiq + +Sidekiq didn't process the CI state change fast enough. Please wait a few +seconds and the status should update automatically. + +#### Bug + +Merge request pipeline statuses can't be retrieved when the following occurs: + +1. A merge request is created +1. The merge request is closed +1. Changes are made in the project +1. The merge request is reopened + +To enable the pipeline status to be properly retrieved, close and reopen the +merge request again. + +## Tips + +Here are some tips to help you be more efficient with merge requests in +the command line. + +### Copy the branch name for local checkout + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. + +The merge request sidebar contains the branch reference for the source branch +used to contribute changes for this merge request. + +To copy the branch reference into your clipboard, select the **Copy branch name** button +(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally +from the command line by running `git checkout <branch-name>`. + +### Checkout merge requests locally through the `head` ref + +A merge request contains all the history from a repository, plus the additional +commits added to the branch associated with the merge request. Here's a few +ways to check out a merge request locally. + +You can check out a merge request locally even if the source +project is a fork (even a private fork) of the target project. + +This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) +that is available for each merge request. It allows checking out a merge +request by using its ID instead of its branch. + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab +13.4, 14 days after a merge request gets closed or merged, the merge request +`head` ref is deleted. This means that the merge request isn't available +for local checkout from the merge request `head` ref anymore. The merge request +can still be re-opened. If the merge request's branch +exists, you can still check out the branch, as it isn't affected. + +#### Checkout locally by adding a Git alias + +Add the following alias to your `~/.gitconfig`: + +```plaintext +[alias] + mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - +``` + +Now you can check out a particular merge request from any repository and any +remote. For example, to check out the merge request with ID 5 as shown in GitLab +from the `origin` remote, do: + +```shell +git mr origin 5 +``` + +This fetches the merge request into a local `mr-origin-5` branch and check +it out. + +#### Checkout locally by modifying `.git/config` for a given repository + +Locate the section for your GitLab remote in the `.git/config` file. It looks +like this: + +```plaintext +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* +``` + +You can open the file with: + +```shell +git config -e +``` + +Now add the following line to the above section: + +```plaintext +fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +In the end, it should look like this: + +```plaintext +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* + fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +Now you can fetch all the merge requests: + +```shell +git fetch origin + +... +From https://gitlab.com/gitlab-org/gitlab-foss.git + * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 + * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 +... +``` + +And to check out a particular merge request: + +```shell +git checkout origin/merge-requests/1 +``` + +All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. + +## Cached merge request count + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). + +WARNING: +This feature might not be available to you. Refer to the previous **version history** note for details. + +In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. + +### Enable or disable cached merge request count **(FREE SELF)** + +Cached merge request count in the left sidebar is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) +can disable it. + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_merge_requests_count) +``` + +To enable it: + +```ruby +Feature.enable(:cached_sidebar_merge_requests_count) +``` diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md new file mode 100644 index 00000000000..0c8dd384b88 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -0,0 +1,142 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: index, reference +--- + +# Suggest changes **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. +> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../../../feature_flags.md), disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. + +As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request +diff threads. Then, the merge request author (or other users with appropriate +[permission](../../../permissions.md)) is able to apply these suggestions with a click, +which generates a commit in the merge request authored by the user that applied them. + +1. Choose a line of code to be changed, add a new comment, then select + the **Insert suggestion** icon in the toolbar: + +  + +1. In the comment, add your suggestion to the pre-populated code block: + +  + +1. Select either **Start a review** or **Add to review** to add your comment to a + [review](index.md), or **Add comment now** to add the comment to the thread immediately. + + The suggestion in the comment can be applied by the merge request author + directly from the merge request: + +  + +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9, + you can opt to add a custom commit message to describe your change. If you don't + specify it, the default commit message is used. It is not supported for [batch suggestions](#batch-suggestions). + +  + +After the author applies a suggestion, it's marked with the **Applied** label, +the thread is automatically resolved, and GitLab creates a new commit +and pushes the suggested change directly into the codebase in the merge request's +branch. [Developer permission](../../../permissions.md) is required to do so. + +## Multi-line suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. + +Reviewers can also suggest changes to multiple lines with a single suggestion +within merge request diff threads by adjusting the range offsets. The +offsets are relative to the position of the diff thread, and specify the +range to be replaced by the suggestion when it is applied. + + + +In the previous example, the suggestion covers three lines above and four lines +below the commented line. When applied, it would replace from 3 lines _above_ +to 4 lines _below_ the commented line, with the suggested change. + + + +NOTE: +Suggestions for multiple lines are limited to 100 lines _above_ and 100 +lines _below_ the commented diff line. This allows for up to 200 changed lines per +suggestion. + +## Code block nested in suggestions + +If you need to make a suggestion that involves a +[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks +instead of the usual three. + + + + + +## Configure the commit message for applied suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. + +GitLab uses a default commit message +when applying suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` + +For example, consider that a user applied 3 suggestions to 2 different files, the +default commit message is: **Apply 3 suggestion(s) to 2 file(s)** + +These commit messages can be customized to follow any guidelines you might have. +To do so, expand the **Merge requests** tab within your project's **General** +settings and change the **Merge suggestions** text: + + + +You can also use following variables besides static text: + +| Variable | Description | Output example | +|------------------------|-------------|----------------| +| `%{branch_name}` | The name of the branch the suggestion(s) was(were) applied to. | `my-feature-branch` | +| `%{files_count}` | The number of file(s) to which suggestion(s) was(were) applied.| **2** | +| `%{file_paths}` | The path(s) of the file(s) suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | +| `%{project_path}` | The project path. | `my-group/my-project` | +| `%{project_name}` | The human-readable name of the project. | **My Project** | +| `%{suggestions_count}` | The number of suggestions applied.| **3** | +| `%{username}` | The username of the user applying suggestion(s). | `user_1` | +| `%{user_full_name}` | The full name of the user applying suggestion(s). | **User 1** | + +For example, to customize the commit message to output +**Addresses user_1's review**, set the custom text to +`Addresses %{username}'s review`. + +NOTE: +Custom commit messages for each applied suggestion is +introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). + +## Batch suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. + +You can apply multiple suggestions at once to reduce the number of commits added +to your branch to address your reviewers' requests. + +1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**: + +  + +1. Add as many additional suggestions to the batch as you wish: + +  + +1. To remove suggestions, select **Remove from batch**: + +  + +1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**: + +  + +WARNING: +Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 147171e8488..c25ee1a8a94 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -23,7 +23,7 @@ MR is merged. Collecting the coverage information is done via GitLab CI/CD's [artifacts reports feature](../../../ci/yaml/README.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. -GitLab will then take the coverage information in all the files and combine it +GitLab then takes the coverage information in all the files and combines it together. For the coverage analysis to work, you have to provide a properly formatted @@ -41,24 +41,24 @@ Other coverage analysis frameworks support the format out of the box, for exampl - [Coverage.py](https://coverage.readthedocs.io/en/coverage-5.0.4/cmd.html#xml-reporting) (Python) Once configured, if you create a merge request that triggers a pipeline which collects -coverage reports, the coverage will be shown in the diff view. This includes reports -from any job in any stage in the pipeline. The coverage will be displayed for each line: +coverage reports, the coverage is shown in the diff view. This includes reports +from any job in any stage in the pipeline. The coverage displays for each line: - `covered` (green): lines which have been checked at least once by tests - `no test coverage` (orange): lines which are loaded but never executed - no coverage information: lines which are non-instrumented or not loaded -Hovering over the coverage bar will provide further information, such as the number +Hovering over the coverage bar provides further information, such as the number of times the line was checked by tests. NOTE: A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds -100 nodes, there can be mismatches or no matches in the Merge Request diff view. +100 nodes, there can be mismatches or no matches in the merge request diff view. ### Artifact expiration By default, the [pipeline artifact](../../../ci/pipelines/pipeline_artifacts.md#storage) used -to draw the visualization on the Merge Request expires **one week** after creation. +to draw the visualization on the merge request expires **one week** after creation. ### Automatic class path correction @@ -69,8 +69,8 @@ For the coverage report to properly match the files displayed on a merge request must contain the full path relative to the project root. But in some coverage analysis frameworks, the generated Cobertura XML has the `filename` path relative to the class package directory instead. -To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser will attempt to build the -full path by doing following: +To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser attempts to build the +full path by doing the following: 1. Extract a portion of the `source` paths from the `sources` element and combine them with the class `filename` path. 1. Check if the candidate path exists in the project. @@ -82,6 +82,14 @@ to the project root: ```shell Auth/User.cs Lib/Utils/User.cs +src/main/java +``` + +In the Cobertura XML, the `filename` attribute in the `class` element assumes the value is a +relative path to project's root. + +```xml +<class name="packet.name" filename="src/main/java" line-rate="0.0" branch-rate="0.0" complexity="5"> ``` And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: @@ -93,16 +101,16 @@ And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR </sources> ``` -The parser will extract `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to +The parser extracts `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to the project root, combining these extracted sources and the class filename. -If for example there is a `class` element with the `filename` value of `User.cs`, the parser will take the first candidate path -that matches which is `Auth/User.cs`. +If for example there is a `class` element with the `filename` value of `User.cs`, the parser takes the first candidate path +that matches, which is `Auth/User.cs`. -For each `class` element, the parser will attempt to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. +For each `class` element, the parser attempts to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. NOTE: -The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser will assume that +The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser assumes that the `filename` of a `class` element contains the full path relative to the project root. ## Example test coverage configurations @@ -153,7 +161,7 @@ coverage-jdk11: stage: visualize image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: - # convert report from jacoco to cobertura + # convert report from jacoco to cobertura, use relative project path - 'python /opt/cover2cover.py target/site/jacoco/jacoco.xml src/main/java > target/site/cobertura.xml' # read the <source></source> tag and prepend the path to every filename attribute - 'python /opt/source2filename.py target/site/cobertura.xml' @@ -193,7 +201,7 @@ coverage-jdk11: stage: visualize image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: - # convert report from jacoco to cobertura + # convert report from jacoco to cobertura, use relative project path - 'python /opt/cover2cover.py build/jacoco/jacoco.xml src/main/java > build/cobertura.xml' # read the <source></source> tag and prepend the path to every filename attribute - 'python /opt/source2filename.py build/cobertura.xml' diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 2c77957c98d..676af4b2881 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -49,11 +49,11 @@ This only applies to commits that are in the most recent version of a merge request - if commits were in a merge request, then rebased out of that merge request, they aren't linked. -## `HEAD` comparison mode for Merge Requests +## `HEAD` comparison mode for merge requests > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) in GitLab 12.10. -Merge Requests, particularly the **Changes** tab, is where source code +Merge requests, particularly the **Changes** tab, is where source code is reviewed and discussed. In circumstances where the target branch was merged into the source branch of the merge request, the changes in the source and target branch can be shown mixed together making it hard to |
