diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-16 21:25:58 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-16 21:25:58 +0300 |
| commit | a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 (patch) | |
| tree | fb69158581673816a8cd895f9d352dcb3c678b1e /doc/user/project/merge_requests | |
| parent | d16b2e8639e99961de6ddc93909f3bb5c1445ba1 (diff) | |
Add latest changes from gitlab-org/gitlab@14-0-stable-eev14.0.0-rc42
Diffstat (limited to 'doc/user/project/merge_requests')
43 files changed, 591 insertions, 337 deletions
diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 09770bd447d..76aff18b00d 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Accessibility Testing +# Accessibility testing **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. @@ -17,11 +17,11 @@ impact of pending code changes. GitLab uses [pa11y](https://pa11y.org/), a free and open source tool for measuring the accessibility of web sites, and has built a simple -[CI job template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). +[CI job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). This job outputs accessibility violations, warnings, and notices for each page analyzed to a file called `accessibility`. -## Accessibility Merge Request widget +## Accessibility merge request widget > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 13.0 behind the disabled [feature flag](../../../administration/feature_flags.md) `:accessibility_report_view`. > - [Feature Flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217372) in GitLab 13.1. @@ -29,7 +29,7 @@ analyzed to a file called `accessibility`. In addition to the report artifact that is created, GitLab will also show the Accessibility Report in the merge request widget area: - + ## Configure Accessibility Testing @@ -38,7 +38,7 @@ on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](htt For GitLab 12.9 and later, to define the `a11y` job, you must [include](../../../ci/yaml/README.md#includetemplate) the -[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) +[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) included with your GitLab installation, as shown below. Add the following to your `.gitlab-ci.yml` file: @@ -67,7 +67,7 @@ For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.js NOTE: For GitLab versions earlier than 12.9, you can use `include:remote` and use a -link to the [current template in `master`](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) +link to the [current template in the default branch](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) NOTE: The job definition provided by the template does not support Kubernetes yet. diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 5917d67c398..63d5119c1b4 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -24,19 +24,17 @@ of the merge request. ## Enabling commit edits from upstream members In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), -this setting is enabled by default. It can be changed by users with Developer -permissions to the source project. Once enabled, upstream members can -retry the pipelines and jobs of the merge request: +this setting is enabled by default. It can be changed by users with the +Developer [role](../../permissions.md) for the source project. After it's enabled, +upstream members can retry the pipelines and jobs of the merge request: -1. While creating or editing a merge request, select the checkbox **Allow - commits from members who can merge to the target branch**. +1. While creating or editing a merge request, scroll to **Contribution** and + then select the **Allow commits from members who can merge to the target branch**. + checkbox. +1. Finish creating your merge request. -  - -1. Once the merge request is created, you can see that commits from members who - can merge to the target branch are allowed. - -  +After you create the merge request, the merge request widget displays a message: +**Members who can merge are allowed to add commits.** ## Pushing to the fork as the upstream member @@ -48,41 +46,39 @@ Assuming that: - The forked project URL is `git@gitlab.com:thedude/awesome-project.git`. - The branch of the merge request is `update-docs`. -Here's how the process would look like: - -1. First, you need to get the changes that the merge request has introduced. - Click the **Check out branch** button that has some pre-populated - commands that you can run. - -  +To find and work with the changes from the fork: -1. Use the copy button to copy the first command and paste them - in your terminal: +1. Open the merge request page, and select the **Overview** tab. +1. Scroll to the merge request widget, and select **Check out branch**: +  +1. In the modal window, select **{copy-to-clipboard}** (**Copy**) for step 1 + to copy the `git fetch` and `git checkout` instructions to your clipboard. + Paste the commands (which look like this example) into your terminal: ```shell git fetch git@gitlab.com:thedude/awesome-project.git update-docs git checkout -b thedude-awesome-project-update-docs FETCH_HEAD ``` - This fetches the branch of the forked project and then create a local branch + These commands fetch the branch from the forked project, and create a local branch based off the fetched branch. -1. Make any changes you want and commit. -1. Push to the forked project: +1. Make your changes to the local copy of the branch, and then commit them. +1. In your terminal, push your local changes back up to the forked project. This + command pushes the local branch `thedude-awesome-project-update-docs` to the + `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository: ```shell git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs ``` - Note the colon (`:`) between the two branches. The above command pushes the - local branch `thedude-awesome-project-update-docs` to the - `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. + Note the colon (`:`) between the two branches. ## Troubleshooting ### Pipeline status unavailable from MR page of forked project -When a user forks a project, the permissions on the forked copy are not copied over +When a user forks a project, the permissions of the forked copy are not copied from the original project. The creator of the fork must grant permissions to the forked copy before members in the upstream project can view or merge the changes in the merge request. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index ac48e44da52..3c47c2af344 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -42,7 +42,7 @@ for more control of the level of oversight and security your project needs, incl - [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). +user interface or with the [Merge request approvals API](../../../../api/merge_request_approvals.md). ## Approve a merge request @@ -97,36 +97,6 @@ Without the approvals, the work cannot merge. Required approvals enable multiple - [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) diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 32f0160771f..1e4b0f659ee 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval rules +# Merge request approval rules **(FREE)** 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: @@ -144,7 +144,7 @@ approve in these ways: [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work) project setting. -### Code owners as eligible approvers +### Code owners as eligible approvers **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. > - Moved to GitLab Premium in 13.9. @@ -162,7 +162,7 @@ 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 +## Merge request approval segregation of duties **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. > - Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 8769f6a7470..97e4b7da396 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval settings +# Merge request approval settings **(FREE)** You can configure the settings for [merge request approvals](index.md) to ensure the approval rules meet your use case. You can also configure diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index aa43d34cdd9..930df65f3fc 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -16,17 +16,17 @@ There are two main ways to have a merge request flow with GitLab: With the protected branch flow everybody works within the same GitLab project. -The project maintainers get Maintainer access and the regular developers get -Developer access. +The project maintainers get the [Maintainer role](../../permissions.md) and the regular developers +get Developer access. -The maintainers mark the authoritative branches as 'Protected'. +Maintainers mark the authoritative branches as 'Protected'. -The developers push feature branches to the project and create merge requests +Developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. -By default, only users with Maintainer access can merge changes into a protected -branch. +By default, only users with the [Maintainer role](../../permissions.md) can merge changes into a +protected branch. **Advantages** @@ -39,14 +39,14 @@ branch. ## Forking workflow -With the forking workflow the maintainers get Maintainer access and the regular +With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it. Developers create forks of the authoritative project and push their feature branches to their own forks. -To get their changes into master they need to create a merge request across +To get their changes into the default branch, they need to create a merge request across forks. **Advantages** diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index b33919c7fbe..d11ad53a9d6 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -40,18 +40,18 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance). +[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. -For an example Performance job, see +For an example Browser Performance job, see [Configuring Browser Performance Testing](#configuring-browser-performance-testing). NOTE: If the Browser Performance report has no data to compare, such as when you add the Browser Performance job in your `.gitlab-ci.yml` for the very first time, -the Browser Performance report widget doesn't show. It must have run at least -once on the target branch (`master`, for example), before it displays in a +the Browser Performance report widget doesn't display. It must have run at least +once on the target branch (`main`, for example), before it displays in a merge request targeting that branch.  @@ -70,27 +70,26 @@ using Docker-in-Docker. include: template: Verify/Browser-Performance.gitlab-ci.yml - performance: + browser_performance: variables: URL: https://example.com ``` 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`. +In GitLab 13.12 and earlier, the job [was named](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) `performance`. The above example: -- Creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you +- Creates a `browser_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) + 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) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. @@ -108,7 +107,7 @@ makes on the given URL, and change the version: include: template: Verify/Browser-Performance.gitlab-ci.yml -performance: +browser_performance: variables: URL: https://www.sitespeed.io/ SITESPEED_VERSION: 13.2.0 @@ -127,7 +126,7 @@ if the `Total Score` metric degrades by 5 points or more: include: template: Verify/Browser-Performance.gitlab-ci.yml -performance: +browser_performance: variables: URL: https://example.com DEGRADATION_THRESHOLD: 5 @@ -140,13 +139,13 @@ The `Total Score` metric is based on sitespeed.io's [coach performance score](ht The above CI YAML configuration is great for testing against static environments, and it can be extended for dynamic environments, but a few extra steps are required: -1. The `performance` job should run after the dynamic environment has started. +1. The `browser_performance` job should run after the dynamic environment has started. 1. In the `review` job: 1. Generate a URL list file with the dynamic URL. 1. Save the file as an artifact, for example with `echo $CI_ENVIRONMENT_URL > environment_url.txt` in your job's `script`. 1. Pass the list as the URL environment variable (which can be a URL or a file containing URLs) - to the `performance` job. + to the `browser_performance` job. 1. You can now run the sitespeed.io container against the desired hostname and paths. @@ -176,7 +175,7 @@ review: except: - master -performance: +browser_performance: dependencies: - review variables: @@ -191,7 +190,7 @@ 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 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). - For 11.5 to 12.3 no template is available and the job has to be defined manually as follows: ```yaml diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index adcf4518209..e594f8048e3 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Changes tab in merge requests +# Changes tab in merge requests **(FREE)** 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 @@ -70,21 +70,6 @@ merge request: 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. @@ -106,10 +91,6 @@ 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. @@ -149,3 +130,42 @@ To disable it: ```ruby Feature.disable(:local_file_reviews) ``` + +## Show merge request conflicts in diff + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5. +> - [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](#enable-or-disable-merge-request-conflicts-in-diff). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +To avoid displaying the changes that are already on target branch in the diff, +we compare the merge request's source branch with HEAD of the target branch. + +When there are conflicts between the source and target branch, we show the +conflicts on the merge request diff as well: + + + +### Enable or disable merge request conflicts in diff **(FREE SELF)** + +Merge request conflicts in diff is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:display_merge_conflicts_in_diff) +``` + +To disable it: + +```ruby +Feature.disable(:display_merge_conflicts_in_diff) +``` diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index eaeef12444e..710638128f3 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -63,10 +63,7 @@ git cherry-pick -m 2 7a39eb0 ### Cherry-pick into a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11. -> - 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](#enable-or-disable-cherry-picking-into-a-project). **(FREE SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0 WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -81,24 +78,10 @@ merge request is from a fork: 1. (Optional) Select **Start a new merge request** if you're ready to create a merge request. 1. Click **Cherry-pick**. -### Enable or disable cherry-picking into a project **(FREE SELF)** +## Related links -Cherry-picking into a project is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:pick_into_project) -``` - -To disable it: - -```ruby -Feature.disable(:pick_into_project) -``` +- The [Commits API](../../../api/commits.md) enables you to add custom messages + to changes you cherry-pick through the API. <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 284d66dd591..27642a9bd5d 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -1,6 +1,6 @@ --- -stage: Verify -group: Testing +stage: Secure +group: Static Analysis 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, howto --- @@ -54,20 +54,25 @@ 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. +> - [Feature enhanced](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0. 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: +the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example: + + + +Previously, an indicator was displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view:  -To disable this feature, a GitLab administrator can run the following in a +To switch to the previous version of this feature, a GitLab administrator can run the following in a [Rails console](../../../administration/operations/rails_console.md): ```ruby # For the instance -Feature.disable(:codequality_mr_diff) +Feature.disable(:codequality_mr_diff_annotations) # For a single project -Feature.disable(:codequality_mr_diff, Project.find(<project id>)) +Feature.disable(:codequality_mr_diff_annotations, Project.find(<project id>)) ``` ## Use cases @@ -527,7 +532,7 @@ This can be due to multiple reasons: - You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not have anything to compare to yet, so no information can be displayed. It only displays after future merge requests have something to compare to. -- Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports have nothing to compare to. +- Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md new file mode 100644 index 00000000000..1bda12468a3 --- /dev/null +++ b/doc/user/project/merge_requests/commits.md @@ -0,0 +1,28 @@ +--- +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 +--- + +# Commits tab in merge requests **(FREE)** + +The **Commits** tab in a merge request displays a sequential list of commits +to the Git branch your merge request is based on. From this page, you can review +full commit messages and copy a commit's SHA when you need to +[cherry-pick changes](cherry_pick_changes.md). + +## 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. + + diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index ce1dac0a96b..430c6488b26 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -168,7 +168,8 @@ Click on **Compare branches and continue** to go to the After forking a project and applying your local changes, complete the following steps to 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. On the top bar, select **Menu > Project**. +1. Select **Your Projects**, then select your fork of the repository. 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. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 459b8fa56ff..ce39f39f0a1 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -67,8 +67,8 @@ 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](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](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). +- Preview continuous integration [pipelines on the merge request widget](widgets.md). +- Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). - 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. @@ -114,9 +114,6 @@ It is also possible to manage multiple assignees: ### Reviewer -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. - WARNING: Requesting a code review is an important part of contributing code. However, deciding who should review your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and @@ -132,44 +129,7 @@ To request a review of a merge request, expand the **Reviewers** select box in the right-hand sidebar. Search for the users you want to request a review from. When selected, GitLab creates a [to-do list item](../../todos.md) for each reviewer. -#### Approval Rule information for Reviewers **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. -> - [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](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: - - - -This example shows reviewers and approval rules in a merge request sidebar: - - - -#### Requesting a new review - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. - -After a reviewer completes their [merge request reviews](../../discussions/index.md), -the author of the merge request can request a new review from the reviewer: - -1. If the right sidebar in the merge request is collapsed, click the - **{chevron-double-lg-left}** **Expand Sidebar** icon to expand it. -1. In the **Reviewers** section, click the **Re-request a review** icon (**{redo}**) - next to the reviewer's name. - -GitLab creates a new [to-do item](../../todos.md) for the reviewer, and sends -them a notification email. - -#### Approval status - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292936) in GitLab 13.10. - -If a user in the reviewer list has approved the merge request, a green tick symbol is -shown to the right of their name. +To learn more, read [Review and manage merge requests](reviews/index.md). ### Merge requests to close issues @@ -193,7 +153,7 @@ enabled by default for all new merge requests, enable it in the This option is also visible in an existing merge request next to the merge request button and can be selected or deselected before merging. -It is only visible to users with [Maintainer permissions](../../permissions.md) +It is only visible to users with the [Maintainer role](../../permissions.md) in the source project. If the user viewing the merge request does not have the correct @@ -216,18 +176,18 @@ open merge request, if the destination branch merges while the merge request is open. Merge requests are often chained in this manner, with one merge request depending on another: -- **Merge request 1**: merge `feature-alpha` into `master`. +- **Merge request 1**: merge `feature-alpha` into `main`. - **Merge request 2**: merge `feature-beta` into `feature-alpha`. These merge requests are usually handled in one of these ways: -- Merge request 1 is merged into `master` first. Merge request 2 is then - retargeted to `master`. +- Merge request 1 is merged into `main` first. Merge request 2 is then + retargeted to `main`. - Merge request 2 is merged into `feature-alpha`. The updated merge request 1, which - now contains the contents of `feature-alpha` and `feature-beta`, is merged into `master`. + now contains the contents of `feature-alpha` and `feature-beta`, is merged into `main`. GitLab retargets up to four merge requests when their target branch is merged into -`master`, so you don't need to perform this operation manually. Merge requests from +`main`, so you don't need to perform this operation manually. Merge requests from forks are not retargeted. The feature today works only on merge. Clicking the **Remove source branch** button diff --git a/doc/user/project/merge_requests/img/allow_collaboration.png b/doc/user/project/merge_requests/img/allow_collaboration.png Binary files differdeleted file mode 100644 index cc13493646d..00000000000 --- a/doc/user/project/merge_requests/img/allow_collaboration.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png Binary files differdeleted file mode 100644 index bc7678b21ec..00000000000 --- a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png Binary files differnew file mode 100644 index 00000000000..a942420d65e --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png diff --git a/doc/user/project/merge_requests/img/commit-button_v13_12.png b/doc/user/project/merge_requests/img/commit-button_v13_12.png Binary files differnew file mode 100644 index 00000000000..be154b9e60b --- /dev/null +++ b/doc/user/project/merge_requests/img/commit-button_v13_12.png diff --git a/doc/user/project/merge_requests/img/conflict_ui_v14_0.png b/doc/user/project/merge_requests/img/conflict_ui_v14_0.png Binary files differnew file mode 100644 index 00000000000..92c532351cb --- /dev/null +++ b/doc/user/project/merge_requests/img/conflict_ui_v14_0.png diff --git a/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png b/doc/user/project/merge_requests/img/merge_request_pipeline.png Binary files differindex ce1d6bab536..ce1d6bab536 100644 --- a/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png +++ b/doc/user/project/merge_requests/img/merge_request_pipeline.png diff --git a/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png Binary files differindex 625d47b1142..625d47b1142 100644 --- a/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png +++ b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png b/doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png Binary files differnew file mode 100644 index 00000000000..65009faf426 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png b/doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png Binary files differnew file mode 100644 index 00000000000..9e6d6c552e5 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png b/doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png Binary files differnew file mode 100644 index 00000000000..a305f5c73f8 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png b/doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png Binary files differnew file mode 100644 index 00000000000..6be64112ac6 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png b/doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png Binary files differnew file mode 100644 index 00000000000..fcfe16bcd97 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index f587ab34d11..b5c51c42ae9 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -17,12 +17,93 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. +To get started, read the [introduction to merge requests](getting_started.md). + +## Merge request tabs + 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**. +important parts of the merge request:  -To get started, read the [introduction to merge requests](getting_started.md). +- **Overview**: Contains the description, notifications from pipelines, and a + discussion area for [comment threads](../../discussions/index.md#resolvable-comments-and-threads) + and [code suggestions](reviews/suggestions.md). The right sidebar provides fields + to add assignees, reviewers, labels, and a milestone to your work, and the + [merge request widgets area](widgets.md) reports results from pipelines and tests. +- **Commits**: Contains a list of commits added to this merge request. For more + information, read [Commits tab in merge requests](commits.md). +- **Pipelines**: If configured, contains a list of recent [GitLab CI/CD](../../../ci/README.md) + pipelines and their status. +- **Changes**: Contains the diffs of files changed by this merge request. You can + [configure the display](changes.md). + +## 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](reviews/index.md#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. + +## Merge request sidebar + +The **Overview** tab of a merge request displays a sidebar. In this sidebar, you +can assign, categorize, and track progress on a merge request: + +- [**Assignee**](getting_started.md#assignee): Designate the directly responsible + individual (DRI) for a merge request. With + [multiple assignees](getting_started.md#multiple-assignees), you can assign a + merge request to more than one person at a time. +- [**Reviewer**](reviews/index.md): Designate a team member to review a merge request. + Higher tiers can assign multiple reviewers, and [require approvals](approvals/index.md) + from these reviewers. +- [**Milestone**](../milestones/index.md): Track time-sensitive changes. +- [**Time tracking**](../time_tracking.md): Time spent on a merge request. +- [**Labels**](../labels.md): Categorize a merge request and display it on + appropriate [issue boards](../issue_board.md). +- **Participants**: A list of users participating or watching a merge request. +- [**Notifications**](../../profile/notifications.md): A toggle to select whether + or not to receive notifications for updates to a merge request. + +## Close a merge request + +If you decide to permanently stop work on a merge request, +GitLab recommends you close the merge request rather than +[delete it](#delete-a-merge-request). Users with +Developer, Maintainer, or Owner [roles](../../permissions.md) in a project +can close merge requests in the project: + +1. Go to the merge request you want to close. +1. Scroll to the comment box at the bottom of the page. +1. Following the comment box, select **Close merge request**. + +GitLab closes the merge request, but preserves records of the merge request, +its comments, and any associated pipelines. + +### Delete a merge request + +GitLab recommends you close, rather than delete, merge requests. + +WARNING: +You cannot undo the deletion of a merge request. + +To delete a merge request: + +1. Sign in to GitLab as a user with the project Owner [role](../../permissions.md). + Only users with this role can delete merge requests in a project. +1. Go to the merge request you want to delete, and select **Edit**. +1. Scroll to the bottom of the page, and select **Delete merge request**. ## Merge request workflows diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 865a18a6a05..d1b697add08 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -46,8 +46,8 @@ The key performance metrics that the merge request widget shows after the test c NOTE: If the Load Performance report has no data to compare, such as when you add the Load Performance job in your `.gitlab-ci.yml` for the very first time, -the Load Performance report widget won't show. It must have run at least -once on the target branch (`master`, for example), before it will display in a +the Load Performance report widget doesn't display. It must have run at least +once on the target branch (`main`, for example), before it displays in a merge request targeting that branch. ## Configure the Load Performance Testing job @@ -87,13 +87,13 @@ Refer to the [k6 documentation](https://k6.io/docs/) for detailed information on When your k6 test is ready, the next step is to configure the load performance testing job in GitLab CI/CD. The easiest way to do this is to use the -[`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml) +[`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml) template that is included with GitLab. NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) -for spec details. The [default shared GitLab.com runners](../../gitlab_com/#linux-shared-runners) +for spec details. The [default shared GitLab.com runners](../../../ci/runners/README.md#linux-shared-runners) likely have insufficient specs to handle most large k6 tests. This template runs the @@ -120,7 +120,7 @@ The above example creates a `load_performance` job in your CI/CD pipeline that r the k6 test. NOTE: -For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). +For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). k6 has [various options](https://k6.io/docs/using-k6/options) to configure how it will run tests, such as what throughput (RPS) to run with, how long the test should run, and so on. Almost all options can be configured in the test itself, but as diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 38d6ba062e4..42de04085a9 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,5 +1,6 @@ --- redirect_to: 'approvals/index.md' +remove_date: '2021-07-27' --- This document was moved to [another location](approvals/index.md). diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 4534ce194bf..21282a55ff2 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -38,7 +38,7 @@ For example, given a project `mycorp/awesome-project` that imports a library at `myfriend/awesome-lib`, adding a feature in `awesome-project` may **also** require changes to `awesome-lib`, and so necessitate two merge requests. Merging the `awesome-project` merge request before the `awesome-lib` one would -break the `master`branch. +break the default branch. The `awesome-project` merge request could be [marked as **Draft**](drafts.md), and the reason for the draft stated included in the comments. However, this 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 b1da336aae9..6c1e33a9ace 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -94,7 +94,7 @@ merge-request-pipeline-job: ``` You should avoid configuration like this, and only use branch (`push`) pipelines -or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#avoid-duplicate-pipelines) +or merge request pipelines, when possible. See [`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines) for details on avoiding two pipelines for a single merge request. ### Skipped pipelines diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 4d5d89d6508..4681ef09388 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -39,8 +39,8 @@ highlighted: After all conflicts have been marked as using 'ours' or 'theirs', the conflict can be resolved. Resolving conflicts merges the target branch of the merge request into the source branch, using the options -chosen. If the source branch is `feature` and the target branch is `master`, -this is similar to performing `git checkout feature; git merge master` locally. +chosen. If the source branch is `feature` and the target branch is `main`, +this is similar to performing `git checkout feature; git merge main` locally. ## Resolve conflicts: inline editor 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 0475996cb9b..b32dce0b230 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,5 +1,6 @@ --- redirect_to: 'reviews/index.md' +remove_date: '2021-08-03' --- This document was moved to [another location](reviews/index.md). diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png Binary files differindex c2aa0689d65..c2aa0689d65 100644 --- a/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png Binary files differindex 3828868965b..3828868965b 100644 --- a/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index e98a230c0de..317202e9303 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -7,29 +7,14 @@ type: index, reference # Review and manage merge requests **(FREE)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. + [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. +to propose changes. Your team leaves [comments](../../../discussions/index.md), and +makes [code suggestions](suggestions.md) you can accept from the user interface. +When your work is reviewed, your team members can choose to accept or reject it. ## Bulk edit merge requests at the project level @@ -136,6 +121,45 @@ If you have a review in progress, you will be presented with the option to **Add  +### Approval Rule information for Reviewers **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. +> - [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](../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: + + + +This example shows reviewers and approval rules in a merge request sidebar: + + + +### Requesting a new review + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. + +After a reviewer completes their [merge request reviews](../../../discussions/index.md), +the author of the merge request can request a new review from the reviewer: + +1. If the right sidebar in the merge request is collapsed, click the + **{chevron-double-lg-left}** **Expand Sidebar** icon to expand it. +1. In the **Reviewers** section, click the **Re-request a review** icon (**{redo}**) + next to the reviewer's name. + +GitLab creates a new [to-do item](../../../todos.md) for the reviewer, and sends +them a notification email. + +#### Approval status + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292936) in GitLab 13.10. + +If a user in the reviewer list has approved the merge request, a green tick symbol is +shown to the right of their name. + ## Semi-linear history merge requests A merge commit is created for every merge, but the branch is only merged if @@ -180,56 +204,6 @@ Multiline comments display the comment's line numbers above the body of the comm  -## 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: @@ -386,32 +360,7 @@ All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) ## 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. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/327319) in GitLab 14.0. 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 index 0c8dd384b88..9409cc569a6 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -140,3 +140,7 @@ to your branch to address your reviewers' requests. WARNING: Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. + +## Related links + +- [Suggestions API](../../../../api/suggestions.md) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 4315e5a0305..47c7e208f2d 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -7,7 +7,7 @@ type: reference, concepts # Squash and merge **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) to GitLab Free in 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from GitLab Premium to GitLab Free in 11.0. With squash and merge you can combine all your merge request's commits into one and retain a clean history. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md new file mode 100644 index 00000000000..775820870f3 --- /dev/null +++ b/doc/user/project/merge_requests/status_checks.md @@ -0,0 +1,179 @@ +--- +stage: Manage +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" +type: reference, concepts +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html' +--- + +# External Status Checks **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0. +> - 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](#enable-or-disable-status-checks). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can create a status check that sends merge request data to third-party tools. +When users create, change, or close merge requests, GitLab sends a notification. The users or automated workflows +can then update the status of merge requests from outside of GitLab. + +With this integration, you can integrate with third-party workflow tools, like +ServiceNow, or the custom tool of your choice. The third-party tool +respond with an associated status. This status is then displayed as a non-blocking +widget within the merge request to surface this status to the merge request author or reviewers +at the merge request level itself. + +The lack of a status check response does not block the merging of a merge request. + +You can configure merge request status checks for each individual project. These are not shared between projects. + +To learn more about use cases, feature discovery, and development timelines, +see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). + +## View the status checks on a project + +Within each project's settings, you can see a list of status checks added to the project: + +1. In your project, go to **Settings > General**. +1. Expand the **Merge requests** section. +1. Scroll down to the **Status checks** sub-section. + + + +This list shows the service name, API URL, and targeted branch. +It also provides actions to allow you to create, edit, or remove status checks. + +## Add or update a status check + +### Add a status check + +Within the **Status checks** sub-section, select the **Add status check** button. +The **Add status check** form is then shown. + + + +Filling in the form and selecting the **Add status check** button creates a new status check. + +### Update a status check + +Within the **Status checks** sub-section, select the **Edit** button +next to the status check you want to edit. +The **Update status check** form is then shown. + + + +Changing the values in the form and selecting the **Update status check** button updates the status check. + +### Form values + +For common form errors see the [troubleshooting](#troubleshooting) section below. + +#### Service name + +This name can be any alphanumerical value and **must** be set. The name **must** be unique for +the project. +The name **has** to be unique for the project. + +#### API to check + +This field requires a URL and **must** use either the HTTP or HTTPs protocols. +We **recommend** using HTTPs to protect your merge request data in transit. +The URL **must** be set and **must** be unique for the project. + +#### Target branch + +If you want to restrict the status check to a single branch, +you can use this field to set this limit. + + + +The branches list is populated from the projects [protected branches](../protected_branches.md). + +You can scroll through the list of branches or use the search box +when there are a lot of branches and the branch you are looking +for doesn't appear immediately. The search box requires +**three** alphanumeric characters to be entered for the search to begin. + +If you want the status check to be applied to **all** merge requests, +you can select the **Any branch** option. + +## Delete a status check + +Within the **Status checks** sub-section, select the **Remove...** button +next to the status check you want to delete. +The **Remove status check?** modal is then shown. + + + +To complete the deletion of the status check you must select the +**Remove status check** button. This **permanently** deletes +the status check and it **will not** be recoverable. + +## Troubleshooting + +### Duplicate value errors + +```plaintext +Name is already taken +--- +External API is already in use by another status check +``` + +On a per project basis, status checks can only use a name or API URL once. +These errors mean that either the status checks name or API URL have already +been used in this projects status checks. + +You must either choose a different +value on the current status check or update the value on the existing status check. + +### Invalid URL error + +```plaintext +Please provide a valid URL +``` + +The API to check field requires the URL provided to use either the HTTP or HTTPs protocols. +You must update the value of the field to meet this requirement. + +### Branch list error during retrieval or search + +```plaintext +Unable to fetch branches list, please close the form and try again +``` + +An unexpected response was received from the branches retrieval API. +As suggested, you should close the form and reopen again or refresh the page. This error should be temporary, although +if it persists please check the [GitLab status page](https://status.gitlab.com/) to see if there is a wider outage. + +## Enable or disable status checks **(ULTIMATE SELF)** + +Status checks are under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:ff_compliance_approval_gates) +# For a single project +Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:ff_compliance_approval_gates) +# For a single project +Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>) +``` + +## Related links + +- [External status checks API](../../../api/status_checks.md) diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 4960e9d9889..e044d50d246 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Test Coverage Visualization +# Test coverage visualization **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249811) in GitLab 13.5. @@ -65,53 +65,65 @@ to draw the visualization on the merge request expires **one week** after creati > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217664) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284822) in GitLab 13.9. -For the coverage report to properly match the files displayed on a merge request diff, the `filename` of a `class` element -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. +The coverage report properly matches changed files only if the `filename` of a `class` element +contains the full path relative to the project root. However, 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 attempts to build the -full path by doing the following: +To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser +attempts to build the full path by: -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. -1. Use the first candidate that matches as the class full path. +- Extracting a portion of the `source` paths from the `sources` element and combining them with the + class `filename` path. +- Checking if the candidate path exists in the project. +- Using the first candidate that matches as the class full path. -As an example scenario, given the project's full path is `test-org/test-project`, and has the following file tree relative -to the project root: +#### Path correction example -```shell -Auth/User.cs -Lib/Utils/User.cs -src/main/java -``` +As an example, a project with: -In the Cobertura XML, the `filename` attribute in the `class` element assumes the value is a -relative path to project's root. +- A full path of `test-org/test-project`. +- The following files relative to the project root: -```xml -<class name="packet.name" filename="src/main/java" line-rate="0.0" branch-rate="0.0" complexity="5"> -``` + ```shell + Auth/User.cs + Lib/Utils/User.cs + src/main/java + ``` -And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: +In the: -```xml -<sources> - <source>/builds/test-org/test-project/Auth</source> - <source>/builds/test-org/test-project/Lib/Utils</source> -</sources> -``` +- Cobertura XML, the `filename` attribute in the `class` element assumes the value is a relative + path to the project's root: -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. + ```xml + <class name="packet.name" filename="src/main/java" line-rate="0.0" branch-rate="0.0" complexity="5"> + ``` -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`. +- `sources` from Cobertura XML, the following paths in the format + `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: -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. + ```xml + <sources> + <source>/builds/test-org/test-project/Auth</source> + <source>/builds/test-org/test-project/Lib/Utils</source> + </sources> + ``` + +The parser: + +- Extracts `Auth` and `Lib/Utils` from the `sources` and uses these to determine the `class` path + relative to the project root. +- Combines these extracted `sources` and the class filename. For example, if 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, 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 is not 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 assumes that -the `filename` of a `class` element contains the full path relative to the project root. +Automatic class path correction only works on `source` paths in the format `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. +The `source` is 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 @@ -157,7 +169,7 @@ test-jdk11: coverage-jdk11: # Must be in a stage later than test-jdk11's stage. # The `visualize` stage does not exist by default. - # Please define it first, or chose an existing stage like `deploy`. + # Please define it first, or choose an existing stage like `deploy`. stage: visualize image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index cc0be389891..55e122dec76 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -6,7 +6,7 @@ type: index description: "Test your code and display reports in merge requests" --- -# Tests and reports in merge requests +# Tests and reports in merge requests **(FREE)** GitLab has the ability to test the changes included in a feature branch and display reports or link to useful information directly from merge requests: diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 676af4b2881..1d196de36e2 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,7 +64,7 @@ In GitLab 12.10, we added a comparison mode, which shows a diff calculated by simulating how it would look like once merged - a more accurate representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down -by selecting **master (HEAD)**. In GitLab 13.9, it +by selecting **main (HEAD)**. In GitLab 13.9, it [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the old default comparison. For technical details, additional information is available in the [developer documentation](../../../development/diffs.md#merge-request-diffs-against-the-head-of-the-target-branch). diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md new file mode 100644 index 00000000000..92b2a8f24ef --- /dev/null +++ b/doc/user/project/merge_requests/widgets.md @@ -0,0 +1,64 @@ +--- +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 +--- + +# Merge request widgets **(FREE)** + +The **Overview** page of a merge request displays status updates from services +that perform actions on your merge request. All subscription levels display a +widgets area, but the content of the area depends on your subscription level +and the services you configure for your project. + +## Pipeline information + +If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, +a [merge request](index.md) displays pipeline information in the widgets area +of the **Overview** tab: + +- 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](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) 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). diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 4b854da116e..8b663b8edf8 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -1,5 +1,6 @@ --- redirect_to: 'drafts.md' +remove_date: '2021-05-19' --- This document was moved to [another location](drafts.md). |
