diff options
Diffstat (limited to 'doc/user/project/merge_requests')
26 files changed, 186 insertions, 240 deletions
diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 8f803f9207c..e67af8dc936 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -9,71 +9,69 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. -If your application offers a web interface and you are using -[GitLab CI/CD](../../../ci/index.md), you can quickly determine the accessibility +If your application offers a web interface, you can use +[GitLab CI/CD](../../../ci/index.md) to determine the accessibility impact of pending code changes. -## Overview - -GitLab uses [pa11y](https://pa11y.org/), a free and open source tool for -measuring the accessibility of web sites, and has built a simple +[Pa11y](https://pa11y.org/) is a free and open source tool for +measuring the accessibility of web sites. GitLab integrates Pa11y into a [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`. +The `a11y` job analyzes a defined set of web pages and reports +accessibility violations, warnings, and notices in a file named +`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. +As of [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), Pa11y uses +[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1). ## 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. -In addition to the report artifact that is created, GitLab will also show the -Accessibility Report in the merge request widget area: +GitLab displays an **Accessibility Report** in the merge request widget area: ![Accessibility merge request widget](img/accessibility_mr_widget_v13_0.png) -## Configure Accessibility Testing - -This example shows how to run [pa11y](https://pa11y.org/) -on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility). +## Configure accessibility testing -For GitLab 12.9 and later, to define the `a11y` job, you must -[include](../../../ci/yaml/index.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) -included with your GitLab installation, as shown below. +You can run Pa11y with GitLab CI/CD using the +[GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility). -Add the following to your `.gitlab-ci.yml` file: +To define the `a11y` job for GitLab 12.9 and later: -```yaml -stages: - - accessibility +1. [Include](../../../ci/yaml/index.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) + from your GitLab installation. +1. Add the following configuration to your `.gitlab-ci.yml` file. -variables: - a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in" + ```yaml + stages: + - accessibility + + variables: + a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in" + + include: + - template: "Verify/Accessibility.gitlab-ci.yml" + ``` -include: - - template: "Verify/Accessibility.gitlab-ci.yml" -``` +1. Customize the `a11y_urls` variable to list the URLs of the web pages to test with Pa11y. -creates an `a11y` job in your CI/CD pipeline, runs -Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each. +The `a11y` job in your CI/CD pipeline generates these files: -The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +- One HTML report per URL listed in the `a11y_urls` variable. +- One file containing the collected report data. In GitLab versions 12.11 and later, this + file is named `gl-accessibility.json`. In GitLab versions 12.10 and earlier, this file + is named [`accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). -A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports. -It includes report data for all URLs scanned. - -NOTE: -For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). +You can [view job artifacts in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). NOTE: -For GitLab versions earlier than 12.9, you can use `include:remote` and use a +For GitLab versions earlier than 12.9, use `include:remote` and 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. +The job definition provided by the template does not support Kubernetes. -It is not yet possible to pass configurations into Pa11y via CI configuration. To change anything, -copy the template to your CI file and make the desired edits. +You cannot pass configurations into Pa11y via CI configuration. +To change the configuration, edit a copy of the template in your CI file. diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 5d1a04e1fe0..b10d6597c1e 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -2,77 +2,99 @@ 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 --- -# Allow collaboration on merge requests across forks **(FREE)** +# Collaborate on merge requests across forks **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17395) in GitLab 10.6. +When you open a merge request from your fork, you can allow upstream +members to collaborate with you on your branch. +When you enable this option, members who have permission to merge to the target branch get +permission to write to the merge request's source branch. -When a user opens a merge request from a fork, they are given the option to allow -upstream members to collaborate with them on the source branch. This allows -the members of the upstream project to make small fixes or rebase branches -before merging, reducing the back and forth of accepting external contributions. +The members of the upstream project can then make small fixes or rebase branches +before merging. This feature is available for merge requests across forked projects that are publicly accessible. -When enabled for a merge request, members with merge access to the target -branch of the project is granted write permissions to the source branch -of the merge request. +## Allow commits from upstream members -## Enabling commit edits from upstream members +> Enabled by default in [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308). -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 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: +As the author of a merge request, you can allow commit edits from +upstream members of the project you're contributing to: 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**. + select the **Allow commits from members who can merge to the target branch** checkbox. 1. Finish creating your merge request. -After you create the merge request, the merge request widget displays a message: -**Members who can merge are allowed to add commits.** +After you create the merge request, the merge request widget displays the message +**Members who can merge are allowed to add commits**. Upstream members can then +commit directly to your branch, as well as retry the pipelines and jobs of the +merge request. -## Pushing to the fork as the upstream member +## Prevent commits from upstream members -If the creator of the merge request has enabled contributions from upstream -members, you can push directly to the branch of the forked repository. +As the author of a merge request, you can prevent commit edits from +upstream members of the project you're contributing to: -Assuming that: +1. While creating or editing a merge request, scroll to **Contribution** and + clear the **Allow commits from members who can merge to the target branch** + checkbox. +1. Finish creating your merge request. + +## Push to the fork as the upstream member -- The forked project URL is `git@gitlab.com:thedude/awesome-project.git`. -- The branch of the merge request is `update-docs`. +You can push directly to the branch of the forked repository if: -To find and work with the changes from the fork: +- The author of the merge request has enabled contributions from upstream + members. +- You have at least the [Developer role](../../permissions.md) in the + upstream project. + +In the following example: + +- The forked repository URL is `git@gitlab.com:contributor/forked-project.git`. +- The branch of the merge request is `fork-branch`. + +To change or add a commit to the contributor's merge request: 1. Open the merge request page, and select the **Overview** tab. -1. Scroll to the merge request widget, and select **Check out branch**: - ![Check out branch button](img/commit-button_v13_12.png) -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: +1. Scroll to the merge request widget, and select **Check out branch**. +1. In the modal window, select **Copy** (**{copy-to-clipboard}**). +1. In your terminal, navigate to your cloned version of the repository, and + paste the commands. For example: ```shell - git fetch git@gitlab.com:thedude/awesome-project.git update-docs - git checkout -b thedude-awesome-project-update-docs FETCH_HEAD + git fetch "git@gitlab.com:contributor/forked-project.git" 'fork-branch' + git checkout -b contributor/fork-branch' FETCH_HEAD ``` - These commands fetch the branch from the forked project, and create a local branch - based off the fetched branch. + Those commands fetch the branch from the forked project, and create a local branch + for you to work on. + +1. Make your changes to your local copy of the branch, and then commit them. +1. Push your local changes to the forked project. The following command pushes + the local branch `contributor/fork-branch` to the `fork-branch` branch of + the `git@gitlab.com:contributor/forked-project.git` repository: -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:contributor/forked-project.git contributor/fork-branch:fork-branch + ``` + + If you have amended or squashed any commits, you must force push. Proceed + with caution as this command rewrites the commit history: ```shell - git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs + git push --force git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch ``` - Note the colon (`:`) between the two branches. + Note the colon (`:`) between the two branches. The general scheme is: + + ```shell + git push <forked_repository_git_url> <local_branch>:<fork_branch> + ``` ## Troubleshooting @@ -89,14 +111,3 @@ going back to the original project: 1. Create a group containing all the upstream members. 1. Go to the **Project information > Members** page in the forked project and invite the newly-created group to the forked project. - -<!-- ## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index f4393b2b76d..129010010e7 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -1,8 +1,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 +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 --- # Merge request approval rules **(PREMIUM)** @@ -146,8 +145,7 @@ approve in these ways: ### 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. +> Moved to GitLab Premium in 13.9. If you add [code owners](../../code_owners.md) to your repository, the owners of files become eligible approvers in the project. To enable this merge request approval rule: diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index a6ca9423df0..1e1c8ccb241 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -1,8 +1,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 +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 --- # Merge request approval settings **(PREMIUM)** @@ -32,8 +31,7 @@ In this section of general settings, you can configure the following settings: ## Prevent approval by author -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. By default, the author of a merge request cannot approve it. To change this setting: @@ -54,8 +52,7 @@ this setting, unless you configure one of these options: ## Prevent approvals by users who add commits -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. By default, users who commit to a merge request can still approve it. At both the project level or [instance level](../../../admin_area/merge_requests_approvals.md) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index e59456e5b34..6668e1736cf 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -63,7 +63,7 @@ on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. 1. First, set up GitLab Runner with a - [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). + [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker). 1. Configure the default Browser Performance Testing CI/CD job as follows in your `.gitlab-ci.yml` file: ```yaml diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index b791bce5749..30d463efa69 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -2,13 +2,11 @@ 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 --- # Code Quality **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. To ensure your project's code stays simple, readable, and easy to contribute to, you can use [GitLab CI/CD](../../../ci/index.md) to analyze your source code quality. @@ -32,8 +30,7 @@ Code Quality: ## Code Quality Widget -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. Going a step further, GitLab can show the Code Quality report right in the merge request widget area if a report from the target branch is available to compare to: @@ -69,11 +66,8 @@ the merge request's diff view displays an indicator next to lines with new Code ## Example configuration This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. -It requires GitLab 11.11 or later, and GitLab Runner 11.5 or later. If you are using -GitLab 11.4 or earlier, you can view the deprecated job definitions in the -[documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). -- Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). +- Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker). - Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running Code Quality analysis more efficiently. In either configuration, the runner must have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. @@ -232,7 +226,7 @@ are configured with `privileged=true`, and they do not expose `docker.sock` into the job container. As a result, socket binding cannot be used to make `docker` available in the context of the job script. -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) was chosen as an operational decision by the runner team, instead of exposing `docker.sock`. ### Disabling the code quality job diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index bffb66755e0..0cc18d2117b 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -67,6 +67,8 @@ GitLab creates a squash commit message with this template: > - [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. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75639) `url`, `approved_by`, and `merged_by` variables in GitLab 14.7. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) `co_authored_by` variable in GitLab 14.7. Commit message templates support these variables: @@ -80,8 +82,13 @@ Commit message templates support these variables: | `%{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.` | +| `%{url}` | Full URL to the merge request. | `https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1` | +| `%{approved_by}` | Line-separated list of the merge request approvers. This value is not updated until the first page refresh after an approval. | `Approved-by: Sidney Jones <sjones@example.com>` <br> `Approved-by: Zhang Wei <zwei@example.com>` | +| `%{merged_by}` | User who merged the merge request. | `Alex Garcia <agarcia@example.com>` | +| `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | -Empty variables that are the only word in a line are removed, along with all newline characters preceding it. +Any line containing only an empty variable is removed. If the line to be removed is both +preceded and followed by an empty line, the preceding empty line is also removed. ## Related topics diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 220049d9a88..6ee02238a22 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -2,7 +2,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto description: "How to create merge requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- @@ -78,7 +77,7 @@ You can create a merge request by running Git commands on your local machine. ```plaintext ... - remote: To create a merge request for docs-new-merge-request, visit: + remote: To create a merge request for my-new-branch, visit: remote: https://gitlab.example.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch ``` @@ -111,10 +110,6 @@ For more information, [see the forking workflow documentation](../repository/for ## By sending an email -> The format of the generated email address changed in GitLab 11.7. - The earlier format is still supported so existing aliases - or contacts still work. - You can create a merge request by sending an email message to GitLab. The merge request target branch is the project's default branch. @@ -142,8 +137,6 @@ A merge request is created. ### Add attachments when creating a merge request by email -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5. - You can add commits to a merge request by adding patches as attachments to the email. All attachments with a filename ending in `.patch` are considered patches and are processed diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 0d87a04461b..3cb50195f5a 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -42,7 +42,7 @@ This template requires: - A project built in Rails that uses RSpec for testing. - CI/CD configured to: - Use a Docker image with Ruby available. - - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#configure-pipelines-for-merge-requests) + - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#prerequisites) - [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results) enabled in the project settings. - A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#override-included-configuration-values) this. diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 078f8048900..cd65fe20e66 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -38,9 +38,12 @@ 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. +You can also rebase without running a CI/CD pipeline. +[Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) GitLab 14.7. + The rebase action is also available as a [quick action command: `/rebase`](../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). -![Fast forward merge request](img/ff_merge_rebase.png) +![Fast forward merge request](img/ff_merge_rebase_v14_7.png) If the target branch is ahead of the source branch and a conflict free rebase is not possible, you need to rebase the @@ -48,6 +51,13 @@ source branch locally before you can do a fast-forward merge. ![Fast forward merge rebase locally](img/ff_merge_rebase_locally.png) +## Fast-forward merges prevent squashing commits + +If your project has enabled fast-forward merges, to merge cleanly, the code in a +merge request cannot use [squashing during merge](squash_and_merge.md). Squashing +is available only when accepting a merge request. Rebasing may be required before +squashing, even though squashing can itself be considered equivalent to rebasing. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 323b7505190..ec509f58723 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -2,7 +2,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: index, reference description: "Getting started with merge requests." --- @@ -92,8 +91,7 @@ and the merge request is added to their #### Multiple assignees **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in GitLab 11.11. -> - Moved to GitLab Premium in 13.9 +> Moved to GitLab Premium in 13.9 Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests @@ -207,7 +205,7 @@ This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitla - When working locally in your branch, add multiple commits and only push when you're done, so GitLab runs only one pipeline for all the commits pushed - at once. By doing so, you save pipeline minutes. + at once. By doing so, you save CI/CD minutes. - Delete feature branches on merge or after merging them to keep your repository clean. - Take one thing at a time and ship the smallest changes possible. By doing so, reviews are faster and your changes are less prone to errors. 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 differdeleted file mode 100644 index be154b9e60b..00000000000 --- a/doc/user/project/merge_requests/img/commit-button_v13_12.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase.png b/doc/user/project/merge_requests/img/ff_merge_rebase.png Binary files differdeleted file mode 100644 index f6139f189ce..00000000000 --- a/doc/user/project/merge_requests/img/ff_merge_rebase.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png Binary files differnew file mode 100644 index 00000000000..3c845d277e4 --- /dev/null +++ b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png diff --git a/doc/user/project/merge_requests/img/squash_edit_form.png b/doc/user/project/merge_requests/img/squash_edit_form.png Binary files differdeleted file mode 100644 index 326d74b68cb..00000000000 --- a/doc/user/project/merge_requests/img/squash_edit_form.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_mr_commits.png b/doc/user/project/merge_requests/img/squash_mr_commits.png Binary files differdeleted file mode 100644 index dfc1ee38435..00000000000 --- a/doc/user/project/merge_requests/img/squash_mr_commits.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_mr_message.png b/doc/user/project/merge_requests/img/squash_mr_message.png Binary files differdeleted file mode 100644 index 8c7dc7886f7..00000000000 --- a/doc/user/project/merge_requests/img/squash_mr_message.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_mr_widget.png b/doc/user/project/merge_requests/img/squash_mr_widget.png Binary files differdeleted file mode 100644 index 81334ca9758..00000000000 --- a/doc/user/project/merge_requests/img/squash_mr_widget.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_squashed_commit.png b/doc/user/project/merge_requests/img/squash_squashed_commit.png Binary files differdeleted file mode 100644 index 7def5339d8a..00000000000 --- a/doc/user/project/merge_requests/img/squash_squashed_commit.png +++ /dev/null diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 7b157aa94d8..40859c6b572 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -103,7 +103,7 @@ job. An example configuration workflow: 1. Set up GitLab Runner to run Docker containers, like the - [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). + [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker). 1. Configure the default Load Performance Testing CI/CD job in your `.gitlab-ci.yml` file. You need to include the template and configure it with CI/CD variables: diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index e6fb619d365..6441ccb73fe 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -2,7 +2,6 @@ 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 --- # Revert changes **(FREE)** @@ -13,11 +12,6 @@ by clicking the **Revert** button in merge requests and commit details. ## Revert a merge request NOTE: -The **Revert** button is available only for merge requests -created in GitLab 8.5 and later. However, you can still revert a merge request -by reverting the merge commit from the list of Commits page. - -NOTE: The **Revert** button is shown only for projects that use the merge method "Merge Commit", which can be set under the project's **Settings > General > Merge request**. [Fast-forward commits](fast_forward_merge.md) diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg Binary files differdeleted file mode 100644 index a4c9df0ebb9..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png Binary files differnew file mode 100644 index 00000000000..2805ef19f2d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index c25b9e15974..1b2a35ba139 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -89,7 +89,7 @@ These commit messages can be customized to follow any guidelines you might have. To do so, expand the **Merge requests** tab within your project's **General** settings and change the **Merge suggestions** text: -![Custom commit message for applied suggestions](img/suggestions_custom_commit_messages_v13_1.jpg) +![Custom commit message for applied suggestions](img/suggestions_custom_commit_messages_v14_7.png) You can also use following variables besides static text: diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 3fe82fb8ef3..f90296e9626 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -2,131 +2,79 @@ 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 --- # Squash and merge **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from GitLab Premium to GitLab Free in 11.0. +As you work on a feature branch, you often create small, self-contained commits. These small commits +help describe the process of building a feature, but can clutter your Git history after the feature +is finished. As you finish features, you can combine these commits and ensure a cleaner merge history +in your Git repository by using the _squash and merge_ strategy. -With squash and merge you can combine all your merge request's commits into one -and retain a clean history. +- Small commits are joined together, making it simpler to [revert all parts of a change](revert_changes.md). +- When the single commit merges into the target branch, it retains the full commit history. +- Your base branch remains clean, and contains meaningful commit messages. -Squashing lets you tidy up the commit history of a branch when accepting a merge -request. It applies all of the changes in the merge request as a single commit, -and then merges that commit using the merge method set for the project. +Each time a branch merges into your base branch, up to two commits are added: -In other words, squashing a merge request turns a long list of commits: +- The single commit created by squashing the commits from the branch. +- A merge commit, unless you have [enabled fast-forward merges](fast_forward_merge.md#enabling-fast-forward-merges) + in your project. Fast-forward merges disable both merge commits and squashing. -![List of commits from a merge request](img/squash_mr_commits.png) +By default, squashed commits contain the following metadata: -Into a single commit on merge: +- Message: Description of the squash commit, or a customized message +- Author: User that created the merge request +- Committer: User who initiated the squash -![A squashed commit followed by a merge commit](img/squash_squashed_commit.png) +Project owners can [create new default messages](commit_templates.md) for all +squash commits and merge commits. -NOTE: -The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in -**Project Settings > General > Merge requests > Merge method > Fast-forward merge**. +## Set default squash options for a merge request -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). +Users with permission to create or edit a merge request can set the default squash options +for a merge request. To do this: -It can also be customized before merging a merge request. +1. Go to the merge request and select **Edit**. +1. Select or clear the **Squash commits when merge request is accepted** checkbox. +1. Select **Save changes**. -![A squash commit message editor](img/squash_mr_message.png) +## Squash commits in a merge request -Squashing also works with the fast-forward merge strategy, see [squashing and fast-forward merge](#squash-and-fast-forward-merge) for more details. +If your project allows you to select squashing options for merge requests, to +squash the commits as part of the merge process: -## Use cases +1. Go to the merge request, and scroll to the merge request reports section that + contains the **Merge** button. +1. Ensure the **Squash commits** checkbox is selected. This checkbox doesn't display + if the project's squashing option is set to either **Do not allow** or **Require**. +1. Optional. To modify either the squash commit message or the merge commit message + (depending on your project configuration), select **Modify commit messages**. +1. When the merge request is ready to merge, select **Merge**. -When working on a feature branch, you sometimes want to commit your current -progress, but don't really care about the commit messages. Those 'work in -progress commits' don't necessarily contain important information and as such -you'd rather not include them in your target branch. +## Configure squash options for a project -With squash and merge, when the merge request is ready to be merged, -all you have to do is enable squashing before you press merge to join -the commits in the merge request into a single commit. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `squash_options`, disabled by default. +> - [Enabled on GitLab.com and self-managed by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/232536) in GitLab 13.8. Feature flag `squash_options` removed. -This way, the history of your base branch remains clean with -meaningful commit messages and: +To configure the default squashing behavior for all merge requests in your project: -- It's simpler to [revert](revert_changes.md) if necessary. -- The merged branch retains the full commit history. - -## Enable squash for a merge request - -Anyone who can create or edit a merge request can choose for it to be squashed -on the merge request form. Users can select or clear the checkbox when they -create the merge request: - -![Squash commits checkbox on edit form](img/squash_edit_form.png) - -After the merge request is submitted, Squash and Merge can still be enabled or disabled -by editing the merge request description: - -1. Scroll to the top of the merge request page and click **Edit**. -1. Scroll down to the end of the merge request form and select the checkbox -**Squash commits when merge request is accepted**. - -This setting can then be overridden at the time of accepting the merge request. -At the end of the merge request widget, next to the **Merge** button, the **Squash commits** checkbox -can be either selected or unselected: - -![Squash commits checkbox on accept merge request form](img/squash_mr_widget.png) - -Note that Squash and Merge might not be available depending on the project's configuration -for [Squash Commit Options](#squash-commits-options). - -## Commit metadata for squashed commits - -The squashed commit has the following metadata: - -- Message: the message of the squash commit, or a customized message. -- Author: the author of the merge request. -- Committer: the user who initiated the squash. - -## Squash and fast-forward merge - -When a project has the [fast-forward merge setting enabled](fast_forward_merge.md#enabling-fast-forward-merges), the merge -request must be able to be fast-forwarded without squashing in order to squash -it. This is because squashing is only available when accepting a merge request, -so a merge request may need to be rebased before squashing, even though -squashing can itself be considered equivalent to rebasing. - -## Squash commits options - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2. -> - Deployed behind a feature flag, disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. -> - Enabled on GitLab.com. -> - Can be enabled per project. -> - Recommended for production use. - -With Squash Commits Options you can configure the behavior of Squash and Merge for your project. -To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. -You can choose from these options, which affect existing and new merge requests -submitted to your project: - -- **Do not allow**: users cannot use Squash and Merge to squash all the commits immediately before - merging. The checkbox to enable or disable it is unchecked and hidden from the users. -- **Allow**: users can enable Squash and Merge on a merge request basis. - The checkbox is unchecked (disabled) by default, but and the user is allowed to enable it. -- **Encourage**: users can enable Squash and Merge on a merge request basis. - The checkbox is checked (enabled) by default to encourage its use, but the user is allowed to - disable it. -- **Require**: Squash and Merge is enabled for all merge requests, so it is always performed. - The checkbox to enable or disable it is checked and hidden from the users. - -The Squash and Merge checkbox is displayed when you create a merge request and when you edit the description of an existing one, except when Squash Commit Options is set to **Do not allow** or **Require**. - -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. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Squash commits when merging** section, select your desired behavior: + - **Do not allow**: Squashing is never performed, and the option is not displayed. + - **Allow**: Squashing is allowed, but deselected by default. + - **Encourage**: Squashing is allowed and selected by default, but can be disabled. + - **Require**: Squashing is always performed. While merge requests display the option + to squash, users cannot change it. +1. Select **Save changes**. ## Related topics -- [Commit message templates](commit_templates.md). +- [Commit message templates](commit_templates.md) +- [Fast-forward merges](fast_forward_merge.md) <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 796ffc7866c..236ec64a4dc 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -39,8 +39,6 @@ changes appears as a system note. ## Find the merge request that introduced a change -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2383) in GitLab 10.5. - When viewing the commit details page, GitLab links to the merge request (or merge requests, if it's in more than one) containing that commit. |