diff options
Diffstat (limited to 'doc/user/project/merge_requests')
18 files changed, 327 insertions, 185 deletions
diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 2bc6d5bb148..8f803f9207c 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -21,6 +21,9 @@ measuring the accessibility of web sites, and has built a simple This job outputs accessibility violations, warnings, and notices for each page analyzed to a file called `accessibility`. +From [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), the version of `pa11y` uses +[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1), which may report more issues. + ## 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`. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index aff55419a88..d873f715557 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -3,7 +3,7 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, concepts -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html' +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/approvals/index.html' --- # Merge request approvals **(FREE)** diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index b422982c0e7..1249aa826fa 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -167,7 +167,7 @@ for protected branches. **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. > - Moved to GitLab Premium in 13.9. -You may need to grant users with [Reporter permissions](../../../permissions.md#project-members-permissions), +You may have to grant users with the Reporter [role](../../../permissions.md#project-members-permissions) permission to approve merge requests before they can merge to a protected branch. Some users (like managers) may not need permission to push or merge code, but still need oversight on proposed work. To enable approval permissions for these users without diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 1c56e91ed6b..56e93741c1a 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -39,7 +39,7 @@ By default, the author of a merge request cannot approve it. To change this sett 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Clear the **Prevent MR approval by the author** checkbox. +1. Clear the **Prevent approval by author** checkbox. 1. Select **Save changes**. Authors can edit the approval rule in an individual merge request and override @@ -64,14 +64,20 @@ their own. To do this: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent MR approvals from users who make commits to the MR** checkbox. +1. Select the **Prevent approvals by users who add commits** checkbox. If this checkbox is cleared, an administrator has disabled it [at the instance level](../../../admin_area/merge_requests_approvals.md), and it can't be changed at the project level. 1. Select **Save changes**. -Even with this configuration, [code owners](../../code_owners.md) who contribute -to a merge request can approve merge requests that affect files they own. +Depending on your version of GitLab, [code owners](../../code_owners.md) who commit +to a merge request may or may not be able to approve the work: + +- In GitLab 13.10 and earlier, [code owners](../../code_owners.md) who commit + to a merge request can approve it, even if the merge request affects files they own. +- In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/331548), + [code owners](../../code_owners.md) who commit + to a merge request cannot approve it, when the merge request affects files they own. To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), read the official Git documentation for an explanation. @@ -84,7 +90,7 @@ on merge requests, you can disable this setting: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Prevent users from modifying MR approval rules in merge requests** checkbox. +1. Select the **Prevent editing approval rules in merge requests** checkbox. 1. Select **Save changes**. This change affects all open merge requests. @@ -102,7 +108,7 @@ permission enables an electronic signature for approvals, such as the one define [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Require user password for approvals** checkbox. +1. Select the **Require user password to approve** checkbox. 1. Select **Save changes**. ## Remove all approvals when commits are added to the source branch @@ -113,7 +119,7 @@ when more changes are added to it: 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select the **Require new approvals when new commits are added to an MR** checkbox. +1. Select the **Remove all approvals when commits are added to the source branch** checkbox. 1. Select **Save changes**. Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) @@ -133,21 +139,23 @@ coverage. To learn more, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). -## Merge request approval settings cascading +## Settings cascading -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.4. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.4. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md). On GitLab.com, this feature is not available. -You should not use this feature for production environments +On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `group_merge_request_approval_settings_feature_flag`. On GitLab.com, this feature is available. You can also enforce merge request approval settings: -- At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups on an instance and, therefore, all - projects. -- On a [top-level group](../../../group/index.md#group-approval-rules), which apply to all subgroups and projects. +- At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups + on an instance and, therefore, all projects. +- On a [top-level group](../../../group/index.md#group-approval-rules), which apply to all subgroups + and projects. -If the settings are inherited by a group or project, they cannot be overridden by the group or project that inherited them. +If the settings are inherited by a group or project, they cannot be changed in the group or project +that inherited them. ## Related links 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 339f67f828f..4ae59a76a9a 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -40,7 +40,7 @@ protected branch. ## Forking workflow With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular -developers get Reporter access to the authoritative repository, which prohibits +developers get the Reporter role on the authoritative repository, which prohibits them from pushing any changes to it. Developers create forks of the authoritative project and push their feature diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index e9f1874eb96..9bfbbd8fc6f 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -343,8 +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/index.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 new file mode 100644 index 00000000000..b615c86288c --- /dev/null +++ b/doc/user/project/merge_requests/commit_templates.md @@ -0,0 +1,51 @@ +--- +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, howto +--- + +# Commit message templates **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. + +## Merge commit message template + +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 +[review suggestions](reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). + +Default merge commit message can be recreated using following template: + +```plaintext +Merge branch '%{source_branch}' into '%{target_branch}' + +%{title} + +%{issues} + +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: + + + +You can use static text and following variables: + +| 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 | + +NOTE: +Empty variables that are the only word in a line will be removed along with all newline characters preceding it. + +Merge commit template field has a limit of 500 characters. This limit only applies to the template +itself. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md new file mode 100644 index 00000000000..dc128f89fcd --- /dev/null +++ b/doc/user/project/merge_requests/conflicts.md @@ -0,0 +1,177 @@ +--- +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 conflicts **(FREE)** + +_Merge conflicts_ happen when the two branches in a merge request (the source and target) each have different +changes, and you must decide which change to accept. In a merge request, Git compares +the two versions of the files line by line. In most cases, GitLab can merge changes +together. However, if two branches both change the same lines, GitLab blocks the merge, +and you must choose which change you want to keep. + +A merge request cannot merge until you either: + +- Create a merge commit. +- Resolve the conflict through a rebase. + + + +## Conflicts you can resolve in the user interface + +If your merge conflict meets all of the following conditions, you can resolve the +merge conflict in the GitLab user interface: + +- The file is text, not binary. +- The file is in a UTF-8 compatible encoding. +- The file does not already contain conflict markers. +- The file, with conflict markers added, is less than 200 KB in size. +- The file exists under the same path in both branches. + +If any file in your merge request contains conflicts, but can't meet all of these +criteria, you must resolve the conflict manually. + +## Conflicts GitLab can't detect + +GitLab does not detect conflicts when both branches rename a file to different names. +For example, these changes don't create a conflict: + +1. On branch `a`, doing `git mv example.txt example1.txt` +1. On branch `b`, doing `git mv example1.txt example3.txt`. + +When these branches merge, both `example1.txt` and `example3.txt` are present. + +## Methods of resolving conflicts + +GitLab shows [conflicts available for resolution](#conflicts-you-can-resolve-in-the-user-interface) +in the user interface, and you can also resolve conflicts locally through the command line: + +- [Interactive mode](#resolve-conflicts-in-interactive-mode): UI method best for + conflicts that only require you to select which version of a line to keep, without edits. +- [Inline editor](#resolve-conflicts-in-the-inline-editor): UI method best for more complex conflicts that require you to + edit lines and manually blend changes together. +- [Command line](#resolve-conflicts-from-the-command-line): provides complete control over the most complex conflicts. + +## Resolve conflicts in interactive mode + +To resolve less-complex conflicts from the GitLab user interface: + +1. Go to your merge request. +1. Select **Overview**, and scroll to the merge request reports section. +1. Find the merge conflicts message, and select **Resolve conflicts**. + GitLab shows a list of files with merge conflicts. The conflicts are + highlighted: + +  +1. For each conflict, select **Use ours** or **Use theirs** to mark the version + of the conflicted lines you want to keep. This decision is known as + "resolving the conflict." +1. Enter a **Commit message**. +1. Select **Commit to source branch**. + +Resolving conflicts merges the target branch of the merge request into the +source branch, using the version of the text you chose. If the source branch is +`feature` and the target branch is `main`, these actions are similar to running +`git checkout feature; git merge main` locally. + +## Resolve conflicts in the inline editor + +Some merge conflicts are more complex, requiring you to manually modify lines to +resolve their conflicts. Use the merge conflict resolution editor to resolve complex +conflicts in the GitLab interface: + +1. Go to your merge request. +1. Select **Overview**, and scroll to the merge request reports section. +1. Find the merge conflicts message, and select **Resolve conflicts**. + GitLab shows a list of files with merge conflicts. +1. Select **Edit inline** to open the editor: +  +1. After you resolve the conflict, enter a **Commit message**. +1. Select **Commit to source branch**. + +## Resolve conflicts from the command line + +While most conflicts can be resolved through the GitLab user interface, some are too complex. +Complex conflicts are best fixed locally, from the command line, to give you the +most control over each change: + +1. Open the terminal and check out your feature branch. For example, `my-feature-branch`: + + ```shell + git checkout my-feature-branch + ``` + +1. [Rebase your branch](../../../topics/git/git_rebase.md#regular-rebase) against the + target branch (here, `main`) so Git prompts you with the conflicts: + + ```shell + git fetch + git rebase origin/main + ``` + +1. Open the conflicting file in your preferred code editor. +1. Find the conflict block: + - It begins with the marker: `<<<<<<< HEAD`. + - Next, it displays your changes. + - The marker `=======` indicates the end of your changes. + - Next, it displays the latest changes in the target branch. + - The marker `>>>>>>>` indicates the end of the conflict. +1. Edit the file: + 1. Choose which version (before or after `=======`) you want to keep. + 1. Delete the version you don't want to keep. + 1. Delete the conflict markers. +1. Save the file. +1. Repeat the process for each file that contains conflicts. +1. Stage your changes in Git: + + ```shell + git add . + ``` + +1. Commit your changes: + + ```shell + git commit -m "Fix merge conflicts" + ``` + +1. Continue the rebase: + + ```shell + git rebase --continue + ``` + + WARNING: + Up to this point, you can run `git rebase --abort` to stop the process. + Git aborts the rebase and rolls back the branch to the state you had before + running `git rebase`. + After you run `git rebase --continue`, you cannot abort the rebase. + +1. [Force-push](../../../topics/git/git_rebase.md#force-push) the changes to your + remote branch. + +## Merge commit strategy + +GitLab resolves conflicts by creating a merge commit in the source branch, but +does not merge it into the target branch. You can then review and test the +merge commit. Verify it contains no unintended changes and doesn't break your build. + +## Related topics + +- [Introduction to Git rebase and force-push](../../../topics/git/git_rebase.md). +- [Git GUI apps](https://git-scm.com/downloads/guis) to help you visualize the + differences between branches and resolve them. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 7edc379399b..078f8048900 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -38,6 +38,8 @@ Now, when you visit the merge request page, you can accept it If a fast-forward merge is not possible but a conflict free rebase is possible, a rebase button is offered. +The rebase action is also available as a [quick action command: `/rebase`](../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). +  If the target branch is ahead of the source branch and a conflict free rebase is diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index cee4df1f61e..006e6d4a8aa 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -172,11 +172,6 @@ is set for deletion, the merge request widget displays the > - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) GitLab 13.10. -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to -[disable the `retarget_merge_requests` flag](../../../administration/feature_flags.md). - In specific circumstances, GitLab can retarget the destination branch of 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 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 differnew file mode 100644 index 00000000000..f18ca640d38 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_commit_message_template_v14_5.png diff --git a/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png b/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png Binary files differdeleted file mode 100644 index 52c715840f1..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png +++ /dev/null diff --git a/doc/user/project/merge_requests/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 differdeleted file mode 100644 index 625d47b1142..00000000000 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 2c062c2c592..54b97eb5732 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -17,75 +17,50 @@ 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). +Read more about [how to get started](getting_started.md). -## Merge request tabs +## View merge requests -Merge requests contain tabs at the top of the page to help you navigate to -important parts of the merge request: +You can view merge requests for your project, group, or yourself. - +### View merge requests for a project -- **Overview**: Contains the description, notifications from pipelines, and a - discussion area for [comment threads](../../discussions/index.md#resolve-a-thread) - 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/index.md) - pipelines and their status. -- **Changes**: Contains the diffs of files changed by this merge request. You can - [configure the display](changes.md). +To view all merge requests for a project: -## View merge requests +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests**. + +Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>g</kbd> + <kbd>m</kbd>. + +### View merge requests for all projects in a group -To view a list of merge requests: +To view merge requests for all projects in a group: -- **Merge requests for a project**: Go to your project and select **Merge requests**, or use - the <kbd>g</kbd> + <kbd>m</kbd> [keyboard shortcut](../../shortcuts.md) from a page in your project. -- **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. -- **Merge requests assigned to you**: On any GitLab page, select **Merge requests** - in the top bar, or use the <kbd>Shift</kbd> + <kbd>m</kbd> - [global keyboard shortcut](../../shortcuts.md). +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Merge requests**. -GitLab displays open merge requests, with tabs to filter the list by open and closed status: +If your group contains subgroups, this view also displays merge requests from the subgroup projects. - +## View all merge requests assigned to you + +To view all merge requests assigned to you: + +1. On the top bar, put your cursor in the **Search** box. +1. From the dropdown list, select **Merge requests assigned to me**. + +Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>m</kbd>. You can [search and filter](../../search/index.md#filter-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. - ## Add changes to a merge request If you have permission to add changes to a merge request, you can add your changes -to an existing merge request in several ways, depending on the complexity of your change and whether you need access to a development environment: +to an existing merge request in several ways, depending on the complexity of your +change and whether you need access to a development environment: -- [Edit changes in the Web IDE](../web_ide/index.md) in your browser. Use this +- [Edit changes in the Web IDE](../web_ide/index.md) in your browser with the + <kbd>.</kbd> [keyboard shortcut](../../shortcuts.md). Use this browser-based method to edit multiple files, or if you are not comfortable with Git commands. You cannot run tests from the Web IDE. - [Edit changes in Gitpod](../../../integration/gitpod.md#launch-gitpod-in-gitlab), if you @@ -158,3 +133,7 @@ For a web developer writing a webpage for your company's website: - [Authorization for merge requests](authorization_for_merge_requests.md) - [Testing and reports](testing_and_reports_in_merge_requests.md) - [GitLab keyboard shortcuts](../../shortcuts.md) +- [Comments and threads](../../discussions/index.md) +- [Suggest code changes](reviews/suggestions.md) +- [Commits](commits.md) +- [CI/CD pipelines](../../../ci/index.md) 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 d7c9c0f73ee..256dde4fa17 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -101,7 +101,7 @@ for details on avoiding two pipelines for a single merge request. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. -When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/index.md#skip-pipeline) prevent +When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent merge requests from being merged. To change this behavior: 1. Navigate to your project's **Settings > General** page. diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 4681ef09388..611f37a949b 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,85 +1,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 +redirect_to: 'conflicts.md' +remove_date: '2022-01-26' --- -# Merge request conflict resolution **(FREE)** +This document was moved to [another location](conflicts.md). -Merge conflicts occur when two branches have different changes that cannot be -merged automatically. - -Git can merge changes between branches in most cases, but -occasionally Git requires your assistance to resolve the -conflicts manually. Typically, this is necessary when people change the same -parts of the same files. - -GitLab prevents merge requests from being merged until all conflicts are -resolved. Conflicts can be resolved locally, or in many cases in GitLab -(see [conflicts available for resolution](#conflicts-available-for-resolution) -for information on when this is available). - - - -NOTE: -GitLab resolves conflicts by creating a merge commit in the source branch that -is not automatically merged into the target branch. The merge -commit can be reviewed and tested before the changes are merged. This prevents -unintended changes entering the target branch without review or breaking the -build. - -## Resolve conflicts: interactive mode - -Clicking **Resolve Conflicts** displays a list of files with conflicts, with conflict sections -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 `main`, -this is similar to performing `git checkout feature; git merge main` locally. - -## Resolve conflicts: inline editor - -Some merge conflicts are more complex, requiring you to manually modify a file to -resolve them. Use the merge conflict resolution editor to resolve complex -conflicts in the GitLab interface. Click **Edit inline** to open the editor. -After you're sure about your changes, click **Commit to source branch**. - - - -## Conflicts available for resolution - -GitLab allows resolving conflicts in a file where all of the below are true: - -- The file is text, not binary -- The file is in a UTF-8 compatible encoding -- The file does not already contain conflict markers -- The file, with conflict markers added, is not over 200 KB in size -- The file exists under the same path in both branches - -If any file in your merge request containing conflicts can't meet all of these -criteria, you can't resolve the merge conflict in the UI. - -Additionally, GitLab does not detect conflicts in renames away from a path. For -example, this does not create a conflict: - -1. On branch `a`, doing `git mv file1 file2` -1. On branch `b`, doing `git mv file1 file3`. - -Instead, both files are present in the branch after the merge request is merged. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +<!-- This redirect file can be deleted after <2022-01-26>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index e6f84f1c357..597dcb3dfb9 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -17,6 +17,10 @@ your merge request, 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. +You can review merge requests from the GitLab interface. If you install the +[GitLab Workflow VS Code extension](../../repository/vscode.md), you can also +review merge requests in Visual Studio Code. + ## Review a merge request > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. @@ -207,7 +211,7 @@ These features are associated with merge requests: When viewing the commit details page, GitLab links to the merge request(s) containing that commit. - [Merge requests versions](../versions.md): Select and compare the different versions of merge request diffs -- [Resolve conflicts](../resolve_conflicts.md): +- [Resolve conflicts](../conflicts.md): GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. - [Revert changes](../revert_changes.md): Revert changes from any commit from a merge request. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index ac1cd57fb99..7bfb8e52279 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -7,14 +7,13 @@ type: index, reference # Suggest changes **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. -> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../../../feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) custom commit messages for suggestions in GitLab 13.9 [with a flag](../../../../administration/feature_flags.md) named `suggestions_custom_commit`. Disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request diff threads. Then, the merge request author (or other users with appropriate -[permission](../../../permissions.md)) is able to apply these suggestions with a click, -which generates a commit in the merge request authored by the user that suggested the changes. +[permission](../../../permissions.md)) can apply these suggestions with a click. +This action generates a commit in the merge request, authored by the user that suggested the changes. 1. Choose a line of code to be changed, add a new comment, then select the **Insert suggestion** icon in the toolbar: @@ -38,14 +37,15 @@ which generates a commit in the merge request authored by the user that suggeste  -After the author applies a suggestion, it's marked with the **Applied** label, -the thread is automatically resolved, and GitLab creates a new commit -and pushes the suggested change directly into the codebase in the merge request's -branch. The [Developer role](../../../permissions.md) is required to do so. +After the author applies a suggestion: -## Multi-line suggestions +1. The suggestion is marked as **Applied**. +1. The thread is resolved. +1. GitLab creates a new commit with the changes. +1. If the user has the [Developer role](../../../permissions.md), GitLab pushes + the suggested change directly into the codebase in the merge request's branch. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. +## Multi-line suggestions Reviewers can also suggest changes to multiple lines with a single suggestion within merge request diff threads by adjusting the range offsets. The @@ -67,9 +67,9 @@ suggestion. ## Code block nested in suggestions -If you need to make a suggestion that involves a -[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks -instead of the usual three. +To add a suggestion that includes a +[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion +in four backticks instead of three:  @@ -95,14 +95,14 @@ You can also use following variables besides static text: | Variable | Description | Output example | |------------------------|-------------|----------------| -| `%{branch_name}` | The name of the branch the suggestion(s) was(were) applied to. | `my-feature-branch` | -| `%{files_count}` | The number of file(s) to which suggestion(s) was(were) applied.| **2** | -| `%{file_paths}` | The path(s) of the file(s) suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | +| `%{branch_name}` | The name of the branch to which suggestions were applied. | `my-feature-branch` | +| `%{files_count}` | The number of files to which suggestions were applied.| **2** | +| `%{file_paths}` | The paths of the file to which suggestions were applied. Paths are separated by commas.| `docs/index.md, docs/about.md` | | `%{project_path}` | The project path. | `my-group/my-project` | | `%{project_name}` | The human-readable name of the project. | **My Project** | | `%{suggestions_count}` | The number of suggestions applied.| **3** | -| `%{username}` | The username of the user applying suggestion(s). | `user_1` | -| `%{user_full_name}` | The full name of the user applying suggestion(s). | **User 1** | +| `%{username}` | The username of the user applying suggestions. | `user_1` | +| `%{user_full_name}` | The full name of the user applying suggestions. | **User 1** | For example, to customize the commit message to output **Addresses user_1's review**, set the custom text to @@ -114,32 +114,32 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. -> - Custom commit messages for batch suggestions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) in GitLab 14.4. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. You can apply multiple suggestions at once to reduce the number of commits added to your branch to address your reviewers' requests. 1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**: -  +  1. Add as many additional suggestions to the batch as you wish: -  +  1. To remove suggestions, select **Remove from batch**: -  +  1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**. You can optionally specify a custom commit message for [batch suggestions](#batch-suggestions) (GitLab 14.4 and later) to describe your change. If you don't specify it, the default commit message is used. -  +  WARNING: Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. |
