diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-12-20 16:37:47 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-12-20 16:37:47 +0300 |
| commit | aee0a117a889461ce8ced6fcf73207fe017f1d99 (patch) | |
| tree | 891d9ef189227a8445d83f35c1b0fc99573f4380 /doc/user/project/merge_requests | |
| parent | 8d46af3258650d305f53b819eabf7ab18d22f59e (diff) | |
Add latest changes from gitlab-org/gitlab@14-6-stable-eev14.6.0-rc42
Diffstat (limited to 'doc/user/project/merge_requests')
19 files changed, 110 insertions, 53 deletions
diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index d873f715557..dddd3925dbb 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -105,7 +105,7 @@ 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)** -## Related links +## Related topics - [Merge request approvals API](../../../../api/merge_request_approvals.md) - [Instance-level approval rules](../../../admin_area/merge_requests_approvals.md) for self-managed installations diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 1249aa826fa..f4393b2b76d 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -63,7 +63,7 @@ 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. 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 diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 56e93741c1a..a6ca9423df0 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -157,7 +157,7 @@ You can also enforce merge request approval settings: If the settings are inherited by a group or project, they cannot be changed in the group or project that inherited them. -## Related links +## Related topics - [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) - [Compliance report](../../../compliance/compliance_report/index.md) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index eff3a5bd99e..e59456e5b34 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -40,7 +40,7 @@ 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/index.md#artifactsreportsbrowser_performance). +[Browser Performance report artifact](../../../ci/yaml/artifacts_reports.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. @@ -89,7 +89,7 @@ The above example: 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/index.md#artifactsreportsbrowser_performance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/artifacts_reports.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. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4a2319774ac..15ba6e9de98 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -76,10 +76,10 @@ merge request is from a fork: 1. Click on the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch:  -1. (Optional) Select **Start a new merge request** if you're ready to create a merge request. +1. Optional. Select **Start a new merge request** if you're ready to create a merge request. 1. Click **Cherry-pick**. -## Related links +## Related topics - The [Commits API](../../../api/commits.md) enables you to add custom messages to changes you cherry-pick through the API. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 9bfbbd8fc6f..b791bce5749 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -87,7 +87,7 @@ include: The above example creates a `code_quality` job in your CI/CD pipeline which scans your source code for code quality issues. The report is saved as a -[Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality) +[Code Quality report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscodequality) that you can later download and analyze. It's also possible to override the URL to the Code Quality image by @@ -343,7 +343,7 @@ It's possible to have a custom tool provide Code Quality reports in GitLab. To do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the - [Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality). + [Code Quality report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscodequality). 1. Configure your tool to generate the Code Quality report artifact as a JSON file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index b615c86288c..bffb66755e0 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -7,15 +7,42 @@ type: reference, howto # Commit message templates **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) squash commit templates in GitLab 14.6. -## Merge commit message template +GitLab uses commit templates to create default messages for specific types of +commits. These templates encourage commit messages to follow a particular format, +or contain specific information. Users can override these templates when merging +a merge request. -As a project maintainer, you're able to configure merge commit message template. It will be used during merge to -create commit message. Template uses similar syntax to +Commit templates use syntax similar to the syntax for [review suggestions](reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). -Default merge commit message can be recreated using following template: +## Configure commit templates + +Change the commit templates for your project if the default templates don't +contain the information you need. + +Prerequisite: + +- You must have at least the Maintainer role for a project. + +To do this: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General** and expand **Merge requests**. +1. Depending on the type of template you want to create, scroll to either + [**Merge commit message template**](#default-template-for-merge-commits) or + [**Squash commit message template**](#default-template-for-squash-commits). +1. For your desired commit type, enter your default message. You can use both static + text and [variables](#supported-variables-in-commit-templates). Each template + is limited to a maximum of 500 characters, though after replacing the templates + with data, the final message may be longer. +1. Select **Save changes**. + +## Default template for merge commits + +The default template for merge commit messages is: ```plaintext Merge branch '%{source_branch}' into '%{target_branch}' @@ -27,25 +54,35 @@ Merge branch '%{source_branch}' into '%{target_branch}' See merge request %{reference} ``` -This commit message 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 commit message template** text: +## Default template for squash commits + +If you have configured your project to [squash commits on merge](squash_and_merge.md), +GitLab creates a squash commit message with this template: + +```plaintext +%{title} +``` + +## Supported variables in commit templates + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) `first_commit` and `first_multiline_commit` variables in GitLab 14.6. - +Commit message templates support these variables: -You can use static text and following variables: +| Variable | Description | Output example | +|----------|-------------|----------------| +| `%{source_branch}` | The name of the branch being merged. | `my-feature-branch` | +| `%{target_branch}` | The name of the branch that the changes are applied to. | `main` | +| `%{title}` | Title of the merge request. | `Fix tests and translations` | +| `%{issues}` | String with phrase `Closes <issue numbers>`. Contains all issues mentioned in the merge request description that match [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). Empty if no issues are mentioned. | `Closes #465, #190 and #400` | +| `%{description}` | Description of the merge request. | `Merge request description.`<br>`Can be multiline.` | +| `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` | +| `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | +| `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge Request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | -| Variable | Description | Output example | -|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| -| `%{source_branch}` | The name of the branch that is being merged. | `my-feature-branch` | -| `%{target_branch}` | The name of the branch that the changes are applied to. | `master` | -| `%{title}` | Title of the merge request. | Fix stuff | -| `%{issues}` | String with phrase "Closes <issue numbers>" with all issues mentioned in the MR description matching [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). It will be empty when no issues were mentioned. | `Closes #465, #190 and #400` | -| `%{description}` | Description of the merge request. | Merge request description.<br>Can be multiline. | -| `%{reference}` | Reference to the merge request. | group-name/project-name!72359 | +Empty variables that are the only word in a line are removed, along with all newline characters preceding it. -NOTE: -Empty variables that are the only word in a line will be removed along with all newline characters preceding it. +## Related topics -Merge commit template field has a limit of 500 characters. This limit only applies to the template -itself. +- [Squash and merge](squash_and_merge.md). diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index ff2e6acf123..10c63421876 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -70,7 +70,7 @@ Open a merge request - You are satisfied the problem is resolved in your private fork. - You are ready to make the confidential commits public. -## Related links +## Related topics - [Confidential issues](../issues/confidential_issues.md) - [Make an epic confidential](../../group/epics/manage_epics.md#make-an-epic-confidential) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 918f9830edc..220049d9a88 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -21,6 +21,10 @@ You can create a merge request from the list of merge requests. 1. Select a source and target branch and then **Compare branches and continue**. 1. Fill out the fields and select **Create merge request**. +NOTE: +Merge requests are designed around a one-to-one (1:1) branch relationship. Only one open merge request may +be associated with a given target branch at a time. + ## From an issue You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). @@ -155,6 +159,8 @@ branch already exists, the patches are applied on top of it. ## Set the default target project +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58093) in GitLab 13.11. + Merge requests have a source and a target project that are the same, unless forking is involved. Creating a fork of the project can cause either of these scenarios when you create a new merge request: diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 006e6d4a8aa..323b7505190 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -88,7 +88,7 @@ Choose an assignee to designate someone as the person responsible 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). +[assigned merge request list](../../search/index.md#search-issues-and-merge-requests). #### Multiple assignees **(PREMIUM)** @@ -136,10 +136,18 @@ To learn more, read [Review a merge request](reviews/index.md). ### Merge requests to close issues -If the merge request is being created to resolve an issue, you can -add a note in the description which sets it to -[automatically close the issue](../issues/managing_issues.md#closing-issues-automatically) -when merged. +To create a merge request to close an issue when it's merged, you can either: + +- [Add a note in the MR description](../issues/managing_issues.md#closing-issues-automatically). +- In the issue, select **Create a merge request**. Then, you can either: + + - Create a new branch and [a draft merge request](../merge_requests/drafts.md) + in one action. The branch is named `issuenumber-title` by default, but you can + choose any name, and GitLab verifies that it's not already in use. The merge request + inherits the milestone and labels of the issue, and is set to automatically + close the issue when it is merged. + - Create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) + only, with its name starting with the issue number. If the issue is [confidential](../issues/confidential_issues.md), you may want to use a different workflow for diff --git a/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png b/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png Binary files differdeleted file mode 100644 index f18ca640d38..00000000000 --- a/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 54b97eb5732..8222d696853 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -74,7 +74,7 @@ change and whether you need access to a development environment: 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 +[delete it](#delete-a-merge-request). The author and assignees of a merge request, and users with Developer, Maintainer, or Owner [roles](../../permissions.md) in a project can close merge requests in the project: diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 1d892a3c2e1..7b157aa94d8 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -28,7 +28,7 @@ GET calls to a popular API endpoint in your application to see how it performs. ## How Load Performance Testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). +[Load Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsload_performance). GitLab checks this report, compares key load performance metrics between the source and target branches, and then shows the information in a merge request widget: @@ -140,7 +140,7 @@ For example, you can override the duration of the test with a CLI option: GitLab only displays the key performance metrics in the MR widget if k6's results are saved via [summary export](https://k6.io/docs/results-visualization/json#summary-export) -as a [Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). +as a [Load Performance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsload_performance). The latest Load Performance artifact available is always used, using the summary values from the test. @@ -161,7 +161,7 @@ such as: ``http.get(`${__ENV.ENVIRONMENT_URL}`)``. For example: 1. In the `review` job: - 1. Capture the dynamic URL and save it into a `.env` file, e.g. `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. + 1. Capture the dynamic URL and save it into a `.env` file, for example, `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. 1. Set the `.env` file to be a [job artifact](../../../ci/pipelines/job_artifacts.md#job-artifacts). 1. In the `load_performance` job: 1. Set it to depend on the review job, so it inherits the environment file. diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 597dcb3dfb9..c34a8116625 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -43,7 +43,7 @@ To start your review: - **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. +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 @@ -72,7 +72,7 @@ When you submit your review, GitLab: ### Resolve or unresolve thread with a comment -Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread)). +Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread). When replying to a comment, a checkbox is displayed to resolve or unresolve the thread after publication. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 7bfb8e52279..c25b9e15974 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -144,6 +144,6 @@ 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 +## Related topics - [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 c3fc2fa871f..3fe82fb8ef3 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -29,11 +29,9 @@ The squashed commit in this example is followed by a merge commit, because the m **Project Settings > General > Merge requests > Merge method > Fast-forward merge**. The squashed commit's default commit message is taken from the merge request title. +You can [edit the default message for squash commits](commit_templates.md). -NOTE: -This only takes effect if there are at least 2 commits. As there is nothing to squash, the commit message does not change if there is only 1 commit. - -It can be customized before merging a merge request. +It can also be customized before merging a merge request.  @@ -126,6 +124,10 @@ NOTE: If your project is set to **Do not allow** Squash and Merge, the users still have the option to squash commits locally through the command line and force-push to their remote branch before merging. +## Related topics + +- [Commit message templates](commit_templates.md). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 08b82462187..f5ebfb3668c 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -181,6 +181,6 @@ You should: - Check the [GitLab status page](https://status.gitlab.com/) if the problem persists, to see if there is a wider outage. -## Related links +## Related topics - [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 b36510c2df8..1f84964c619 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -29,7 +29,7 @@ between pipeline completion and the visualization loading on the page. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to -[`artifacts:reports:cobertura`](../../../ci/yaml/index.md#artifactsreportscobertura). +[`artifacts:reports:cobertura`](../../../ci/yaml/artifacts_reports.md#artifactsreportscobertura). This format was originally developed for Java, but most coverage analysis frameworks for other languages have plugins to add support for it, like: @@ -52,10 +52,15 @@ from any job in any stage in the pipeline. The coverage displays for each line: Hovering over the coverage bar provides further information, such as the number of times the line was checked by tests. -NOTE: +### Limits + 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. +A single Cobertura XML file can be no more than 10MiB. For large projects, split the Cobertura XML into +smaller files. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328772) for more details. +When submitting many files, it can take a few minutes for coverage to show on a merge request. + ### Artifact expiration By default, the [pipeline artifact](../../../ci/pipelines/pipeline_artifacts.md#storage) used diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 3922ee4d770..796ffc7866c 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -2,10 +2,9 @@ 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: reference, concepts --- -# Merge requests versions +# Merge requests versions **(FREE)** Every time you push to a branch that is tied to a merge request, a new version of merge request diff is created. When you visit a merge request that contains |
