Merge branch 'docs-merge-requests-1' into 'master'

Revamp Merge Request documentation

See merge request gitlab-org/gitlab!18644

doc/README.md

@@ -189,8 +189,8 @@ The following documentation relates to the DevOps **Create** stage:
 #### Merge Requests
 
 | Create Topics - Merge Requests                                                                                                              | Description                                                                                                                           |
-|:------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------|
-| [Checking out merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally) | Tips for working with merge requests locally.                                                                                                     |
+|:--------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------|
+| [Checking out merge requests locally](user/project/merge_requests/reviewing_and_managing_merge_requests.md#checkout-merge-requests-locally) | Tips for working with merge requests locally.                                                                                         |
 | [Cherry-picking](user/project/merge_requests/cherry_pick_changes.md)                                                                        | Use GitLab for cherry-picking changes.                                                                                                |
 | [Merge request thread resolution](user/discussions/index.md#moving-a-single-thread-to-a-new-issue)                                          | Resolve threads, move threads in a merge request to an issue, and only allow merge requests to be merged if all threads are resolved. |
 | [Merge requests](user/project/merge_requests/index.md)                                                                                      | Merge request management.                                                                                                             |

doc/administration/incoming_email.md

@@ -7,7 +7,7 @@ GitLab has several features based on receiving incoming emails:
 - [New issue by email](../user/project/issues/managing_issues.md#new-issue-via-email):
   allow GitLab users to create a new issue by sending an email to a
   user-specific email address.
-- [New merge request by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email):
+- [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#create-new-merge-requests-by-email):
   allow GitLab users to create a new merge request by sending an email to a
   user-specific email address.
 - [Service Desk](../user/project/service_desk.md): provide e-mail support to
@@ -79,7 +79,7 @@ email address in order to sign up.
 If you also host a public-facing GitLab instance at `hooli.com` and set your
 incoming email domain to `hooli.com`, an attacker could abuse the "Create new
 issue by email" or
-"[Create new merge request by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email)"
+"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#create-new-merge-requests-by-email)"
 features by using a project's unique address as the email when signing up for
 Slack, which would send a confirmation email, which would create a new issue or
 merge request on the project owned by the attacker, allowing them to click the

doc/administration/index.md

@@ -119,7 +119,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. **(PREMIUM ONLY)**
 - [Incoming email](incoming_email.md): Configure incoming emails to allow
   users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#new-issue-via-email) and
-  [merge requests by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email), and to enable [Service Desk](../user/project/service_desk.md).
+  [merge requests by email](../user/project/merge_requests/creating_merge_requests.md#create-new-merge-requests-by-email), and to enable [Service Desk](../user/project/service_desk.md).
   - [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a
   basic Postfix mail server with IMAP authentication on Ubuntu for incoming
   emails.

doc/ci/README.md

@@ -132,7 +132,7 @@ Its feature set is listed on the table below according to DevOps stages.
 | [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)** | Check your Docker containers for known vulnerabilities.|
 | [Dependency Scanning](../user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. |
 | [License Compliance](../user/application_security/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. |
-| [Security Test reports](../user/project/merge_requests/index.md#security-reports-ultimate) **(ULTIMATE)** | Check for app vulnerabilities. |
+| [Security Test reports](../user/application_security/index.md) **(ULTIMATE)** | Check for app vulnerabilities. |
 
 ## Examples
 

doc/ci/introduction/index.md

@@ -207,7 +207,7 @@ With GitLab CI/CD you can also:
 - Deploy your app to different [environments](../environments.md).
 - Install your own [GitLab Runner](https://docs.gitlab.com/runner/).
 - [Schedule pipelines](../../user/project/pipelines/schedules.md).
-- Check for app vulnerabilities with [Security Test reports](../../user/project/merge_requests/index.md#security-reports-ultimate). **(ULTIMATE)**
+- Check for app vulnerabilities with [Security Test reports](../../user/application_security/index.md). **(ULTIMATE)**
 
 To see all CI/CD features, navigate back to the [CI/CD index](../README.md).
 

doc/development/code_review.md

@@ -170,8 +170,8 @@ Maintainers should check before merging if the merge request is approved by the
 required approvers.
 
 Maintainers must check before merging if the merge request is introducing new
-vulnerabilities, by inspecting the list in the Merge Request [Security
-Widget](../user/project/merge_requests/index.md#security-reports-ultimate).
+vulnerabilities, by inspecting the list in the Merge Request
+[Security Widget](../user/application_security/index.md).
 When in doubt, a [Security Engineer](https://about.gitlab.com/company/team/) can be involved. The list of detected
 vulnerabilities must be either empty or containing:
 

doc/user/admin_area/diff_limits.md

@@ -6,7 +6,7 @@ type: reference
 
 You can set a maximum size for display of diff files (patches).
 
-For details about diff files, [View changes between files](../project/merge_requests/index.md#view-changes-between-file-versions).
+For details about diff files, [View changes between files](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-changes-between-file-versions).
 
 ## Maximum diff patch size
 

doc/user/group/index.md

@@ -75,7 +75,7 @@ By doing so:
 ## Issues and merge requests within a group
 
 Issues and merge requests are part of projects. For a given group, you can view all of the
-[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all projects in that group,
+[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group) across all projects in that group,
 together in a single list view.
 
 ### Bulk editing issues and merge requests

doc/user/index.md

@@ -50,10 +50,10 @@ GitLab is a Git-based platform that integrates a great number of essential tools
 With GitLab Enterprise Edition, you can also:
 
 - Provide support with [Service Desk](project/service_desk.md).
-- Improve collaboration with
-  [Merge Request Approvals](project/merge_requests/index.md#merge-request-approvals-starter),
-  [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md),
-  and [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards).
+- Improve collaboration with:
+  - [Merge Request Approvals](project/merge_requests/merge_request_approvals.md). **(STARTER)**
+  - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). **(STARTER)**
+  - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards).
 - Create formal relationships between issues with [Related Issues](project/issues/related_issues.md).
 - Use [Burndown Charts](project/milestones/burndown_charts.md) to track progress during a sprint or while working on a new version of their software.
 - Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Global Search](search/advanced_global_search.md) and [Advanced Syntax Search](search/advanced_search_syntax.md) for faster, more advanced code search across your entire GitLab instance.

doc/user/project/merge_requests/creating_merge_requests.md

+---
+type: index, reference
+---
+
+# Creating merge requests
+
+Merge requests are the primary method of making changes to files in a GitLab project.
+Changes are proposed by creating and submitting a merge request, which is then
+[reviewed, and accepted (or rejected)](reviewing_and_managing_merge_requests.md),
+all within GitLab.
+
+## Creating new merge requests
+
+You can start creating a new merge request by clicking the **New merge request** button
+on the **Merge Requests** page in a project. Then you must choose the source project and
+branch that contain your changes, and the target project and branch where you want to merge
+the changes into. Click on **Compare branches and continue** to go to the next step
+and start filling in the merge request details.
+
+When viewing the commits on a branch other than master in **Repository > Commits**, you
+can click on the **Create merge request** button, and a new merge request will be started
+using the current branch as the source, and `master` in the current project as the target.
+
+If you have recently pushed changes to GitLab, the **Create merge request** button will
+also appear in the top right of the:
+
+- **Project** page.
+- **Repository > Files** page.
+- **Merge Requests** page.
+
+In this case, the merge request will use the most recent branch you pushed changes
+to as the source branch, and `master` in the current project as the target.
+
+## Workflow for new merge requests
+
+On the **New Merge Request** page, you can start by filling in the title and description
+for the merge request. If there are are already commits on the branch, the title will
+be pre-filled with the first line of the first commit message, and the description will
+be pre-filled with any additional lines in the commit message. The title is the only
+field that is mandatory in all cases.
+
+From here, you can also:
+
+- Set the merge request as a [work in progress](work_in_progress_merge_requests.md).
+- Select the [assignee](#assignee), or [assignees](#multiple-assignees-starter). **(STARTER)**
+- Select a [milestone](../milestones/index.md).
+- Select [labels](../labels.md).
+- Add any [merge request dependencies](merge_request_dependencies.md). **(PREMIUM)**
+- Select [approval options](merge_request_approvals.md). **(STARTER)**
+- Verify the source and target branches are correct.
+- Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option.
+- Enable the [squash commits when merge request is accepted](squash_and_merge.md) option.
+- If the merge request is from a fork, enable [Allow collaboration on merge requests across forks](allow_collaboration.md).
+
+Many of these can be set when pushing changes from the command line, with
+[Git push options](../push_options.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 will set it to [automatically close the issue](../issues/managing_issues.md#closing-issues-automatically)
+when merged.
+
+If the issue is [confidential](../issues/confidential_issues.md), you may want to
+use a different workflow for [merge requests for confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues),
+to prevent confidential information from being exposed.
+
+## Assignee
+
+Choose an assignee to designate someone as the person responsible for the first
+[review of the merge request](reviewing_and_managing_merge_requests.md). Open the
+drop down box to search for the user you wish to assign, and the merge request will be
+added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests).
+
+### Multiple assignees **(STARTER)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/).
+
+Multiple people often review merge requests at the same time. GitLab allows you to
+have multiple assignees for merge requests to indicate everyone that is reviewing or
+accountable for it.
+
+![multiple assignees for merge requests sidebar](img/multiple_assignees_for_merge_requests_sidebar.png)
+
+To assign multiple assignees to a merge request:
+
+1. From a merge request, expand the right sidebar and locate the **Assignees** section.
+1. Click on **Edit** and from the dropdown menu, select as many users as you want
+   to assign the merge request to.
+
+Similarly, assignees are removed by deselecting them from the same dropdown menu.
+
+It's also possible to manage multiple assignees:
+
+- When creating a merge request.
+- Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics).
+
+## Deleting the source branch
+
+When creating a merge request, select the "Delete source branch when merge
+request accepted" option and the source branch will be deleted when the merge
+request is merged. To make this option enabled by default for all new merge
+requests, enable it in the [project's settings](../settings/index.md#merge-request-settings).
+
+This option is also visible in an existing merge request next to the merge
+request button and can be selected/deselected before merging. It's only visible
+to users with [Maintainer permissions](../../permissions.md) in the source project.
+
+If the user viewing the merge request does not have the correct permissions to
+delete the source branch and the source branch is set for deletion, the merge
+request widget will show the "Deletes source branch" text.
+
+![Delete source branch status](img/remove_source_branch_status.png)
+
+## Create new merge requests by email
+
+_This feature needs [incoming email](../../../administration/incoming_email.md)
+to be configured by a GitLab administrator to be available for CE/EE users, and
+it's available on GitLab.com._
+
+You can create a new merge request by sending an email to a user-specific email
+address. The address can be obtained on the merge requests page by clicking on
+a **Email a new merge request to this project** button. The subject will be
+used as the source branch name for the new merge request and the target branch
+will be the default branch for the project. The message body (if not empty)
+will be used as the merge request description. You need
+["Reply by email"](../../../administration/reply_by_email.md) enabled to use
+this feature. If it's not enabled to your instance, you may ask your GitLab
+administrator to do so.
+
+This is a private email address, generated just for you. **Keep it to yourself**
+as anyone who gets ahold of it can create issues or merge requests as if they were you.
+You can add this address to your contact list for easy access.
+
+![Create new merge requests by email](img/create_from_email.png)
+
+_In GitLab 11.7, we updated the format of the generated email address.
+However the older format is still supported, allowing existing aliases
+or contacts to continue working._
+
+### Adding patches when creating a merge request via e-mail
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22723) in GitLab 11.5.
+
+You can add commits to the merge request being created by adding
+patches as attachments to the email. All attachments with a filename
+ending in `.patch` will be considered patches and they will be processed
+ordered by name.
+
+The combined size of the patches can be 2MB.
+
+If the source branch from the subject does not exist, it will be
+created from the repository's HEAD or the specified target branch to
+apply the patches. The target branch can be specified using the
+[`/target_branch` quick action](../quick_actions.md). If the source
+branch already exists, the patches will be applied on top of it.

doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md

+---
+type: index, reference
+---
+
+# Reviewing and managing merge requests
+
+Merge requests are the primary method of making changes to files in a GitLab project.
+Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md),
+which is then reviewed, and accepted (or rejected).
+
+## View project merge requests
+
+View all the merge requests within a project by navigating to **Project > Merge Requests**.
+
+When you access your project's merge requests, GitLab will present them in a list,
+and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#issues-and-merge-requests-per-project).
+
+![Project merge requests list view](img/project_merge_requests_list_view.png)
+
+## View merge requests for all projects in a group
+
+View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs.
+
+You can [search and filter the results](../../search/index.md#issues-and-merge-requests-per-group) from here.
+
+![Group Issues list view](img/group_merge_requests_list_view.png)
+
+## Semi-linear history merge requests
+
+A merge commit is created for every merge, but the branch is only merged if
+a fast-forward merge is possible. This ensures that if the merge request build
+succeeded, the target branch build will also succeed after merging.
+
+Navigate to a project's settings, select the **Merge commit with semi-linear history**
+option under **Merge Requests: Merge method** and save your changes.
+
+## View changes between file versions
+
+The **Changes** tab, below the main merge request details and next to the discussion tab,
+shows the changes to files between branches or commits. This view of changes to a
+file is also known as a **diff**. By default, the diff view compares the file in the
+merge request branch and the file in the target branch.
+
+The diff view includes the following:
+
+- The file's name and path.
+- The number of lines added and deleted.
+- Buttons for the following options:
+  - Toggle comments for this file; useful for inline reviews.
+  - Edit the file in the merge request's branch.
+  - Show full file, in case you want to look at the changes in context with the rest of the file.
+  - View file at the current commit.
+  - Preview the changes with [Review Apps](../../../ci/review_apps/index.md).
+- The changed lines, with the specific changes highlighted.
+
+![Example screenshot of a source code diff](img/merge_request_diff_v12_2.png)
+
+### Merge request diff file navigation
+
+When reviewing changes in the **Changes** tab the diff can be navigated using
+the file tree or file list. As you scroll through large diffs with many
+changes, you can quickly jump to any changed file using the file tree or file
+list.
+
+![Merge request diff file navigation](img/merge_request_diff_file_navigation.png)
+
+### Incrementally expand merge request diffs
+
+By default, the diff shows only the parts of a file which are changed.
+To view more unchanged lines above or below a change click on the
+**Expand up** or **Expand down** icons. You can also click on **Show all lines**
+to expand the entire file.
+
+![Incrementally expand merge request diffs](img/incrementally_expand_merge_request_diffs_v12_2.png)
+
+### Ignore whitespace changes in Merge Request diff view
+
+If you click the **Hide whitespace changes** button, you can see the diff
+without whitespace changes (if there are any). This is also working when on a
+specific commit page.
+
+![MR diff](img/merge_request_diff.png)
+
+>**Tip:**
+You can append `?w=1` while on the diffs page of a merge request to ignore any
+whitespace changes.
+
+## Commenting on any file line in merge requests
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13950) in GitLab 11.5.
+
+GitLab provides a way of leaving comments in any part of the file being changed
+in a Merge Request. To do so, click the **...** button in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line.
+
+![Comment on any diff file line](img/comment-on-any-diff-line.png)
+
+## Live preview with Review Apps
+
+If you configured [Review Apps](https://about.gitlab.com/product/review-apps/) for your project,
+you can preview the changes submitted to a feature-branch through a merge request
+in a per-branch basis. No need to checkout the branch, install and preview locally;
+all your changes will be available to preview by anyone with the Review Apps link.
+
+With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the
+merge request widget takes you directly to the pages changed, making it easier and
+faster to preview proposed modifications.
+
+[Read more about Review Apps](../../../ci/review_apps/index.md).
+
+## Pipeline status in merge requests
+
+If you've set up [GitLab CI/CD](../../../ci/README.md) in your project,
+you will be able to see:
+
+- Both pre and post-merge pipelines and the environment information if any.
+- Which deployments are in progress.
+
+If there's an [environment](../../../ci/environments.md) and the application is
+successfully deployed to it, the deployed environment and the link to the
+Review App will be shown as well.
+
+### Post-merge pipeline status
+
+When a merge request is merged, you can see the post-merge pipeline status of
+the branch the merge request was merged into. For example, when a merge request
+is merged into the master branch and then triggers a deployment to the staging
+environment.
+
+Deployments that are ongoing will be shown, as well as the deploying/deployed state
+for environments. If it's the first time the branch is deployed, the link
+will return a `404` error until done. During the deployment, the stop button will
+be disabled. If the pipeline fails to deploy, the deployment info will be hidden.
+
+![Merge request pipeline](img/merge_request_pipeline.png)
+
+For more information, [read about pipelines](../../../ci/pipelines.md).
+
+## Troubleshooting
+
+Sometimes things don't go as expected in a merge request, here are some
+troubleshooting steps.
+
+### Merge request cannot retrieve the pipeline status
+
+This can occur if Sidekiq doesn't pick up the changes fast enough.
+
+#### Sidekiq
+
+Sidekiq didn't process the CI state change fast enough. Please wait a few
+seconds and the status will update automatically.
+
+#### Bug
+
+Merge Request pipeline statuses can't be retrieved when the following occurs:
+
+1. A Merge Request is created
+1. The Merge Request is closed
+1. Changes are made in the project
+1. The Merge Request is reopened
+
+To enable the pipeline status to be properly retrieved, close and reopen the
+Merge Request again.
+
+## Tips
+
+Here are some tips that will help you be more efficient with merge requests in
+the command line.
+
+> **Note:**
+This section might move in its own document in the future.
+
+### Checkout merge requests locally
+
+A merge request contains all the history from a repository, plus the additional
+commits added to the branch associated with the merge request. Here's a few
+tricks to checkout a merge request locally.
+
+Please note that you can checkout a merge request locally even if the source
+project is a fork (even a private fork) of the target project.
+
+#### Checkout locally by adding a Git alias
+
+Add the following alias to your `~/.gitconfig`:
+
+```
+[alias]
+    mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
+```
+
+Now you can check out a particular merge request from any repository and any
+remote. For example, to check out the merge request with ID 5 as shown in GitLab
+from the `origin` remote, do:
+
+```
+git mr origin 5
+```
+
+This will fetch the merge request into a local `mr-origin-5` branch and check
+it out.
+
+#### Checkout locally by modifying `.git/config` for a given repository
+
+Locate the section for your GitLab remote in the `.git/config` file. It looks
+like this:
+
+```
+[remote "origin"]
+  url = https://gitlab.com/gitlab-org/gitlab-foss.git
+  fetch = +refs/heads/*:refs/remotes/origin/*
+```
+
+You can open the file with:
+
+```
+git config -e
+```
+
+Now add the following line to the above section:
+
+```
+fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
+```
+
+In the end, it should look like this:
+
+```
+[remote "origin"]
+  url = https://gitlab.com/gitlab-org/gitlab-foss.git
+  fetch = +refs/heads/*:refs/remotes/origin/*
+  fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
+```
+
+Now you can fetch all the merge requests:
+
+```
+git fetch origin
+
+...
+From https://gitlab.com/gitlab-org/gitlab-foss.git
+ * [new ref]         refs/merge-requests/1/head -> origin/merge-requests/1
+ * [new ref]         refs/merge-requests/2/head -> origin/merge-requests/2
+...
+```
+
+And to check out a particular merge request:
+
+```
+git checkout origin/merge-requests/1
+```
+
+All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script.

doc/user/project/merge_requests/versions.md

@@ -35,6 +35,17 @@ changes appears as a system note.
 
 ![Merge request versions system note](img/versions_system_note.png)
 
+## 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 will link to the merge request (or
+merge requests, if it's in more than one) containing that commit.
+
+This only applies to commits that are in the most recent version of a merge
+request - if a commit was in a merge request, then rebased out of that merge
+request, they will not be linked.
+
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues

doc/user/project/settings/index.md

@@ -53,7 +53,7 @@ Set up your project's merge request settings:
 - Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **(STARTER)**
 - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md).
 - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved).
-- Enable [`delete source branch after merge` option by default](../merge_requests/index.md#deleting-the-source-branch)
+- Enable [`delete source branch after merge` option by default](../merge_requests/creating_merge_requests.md#deleting-the-source-branch)
 
 ![project's merge request settings](img/merge_requests_settings.png)