Merge branch 'selhorn-creating-mrs-1' into 'master'

Edited "Create MRs" for style and CTRT

See merge request gitlab-org/gitlab!65108

doc/administration/incoming_email.md

@@ -13,7 +13,7 @@ GitLab has several features based on receiving incoming email messages:
 - [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/creating_merge_requests.md#new-merge-request-by-email):
+- [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-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 email support to
@@ -95,7 +95,7 @@ email address 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/creating_merge_requests.md#new-merge-request-by-email)"
+"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email)"
 features by using a project's unique address as the email when signing up for
 Slack. This 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

@@ -134,7 +134,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.
 - [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/creating_merge_requests.md#new-merge-request-by-email), and to enable [Service Desk](../user/project/service_desk.md).
+  [merge requests by email](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-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/user/project/merge_requests/creating_merge_requests.md

@@ -7,189 +7,155 @@ description: "How to create merge requests in GitLab."
 disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html'
 ---
 
-# How to create a merge request **(FREE)**
+# Creating merge requests **(FREE)**
 
-Before creating a merge request, read through an
-[introduction to merge requests](getting_started.md)
-to familiarize yourself with the concept, the terminology,
-and to learn what you can do with them.
+There are many different ways to create a merge request.
 
-Every merge request starts by creating a branch. You can either
-do it locally through the [command line](#new-merge-request-from-your-local-environment), via a Git CLI application,
-or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through-the-ui).
+## From the merge request list
 
-This document describes the several ways to create a merge request.
+You can create a merge request from the list of merge requests.
 
-When you start a new merge request, regardless of the method,
-you are taken to the [**New merge request** page](#new-merge-request-page)
-to fill it with information about the merge request.
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left menu, select **Merge requests**.
+1. In the top right, select **New merge request**.
+1. Select a source and target branch and then **Compare branches and continue**.
+1. Fill out the fields and select **Create merge request**.
 
-If you push a new branch to GitLab, also regardless of the method,
-you can click the [**Create merge request**](#create-merge-request-button)
-button and start a merge request from there.
+## From an issue
 
-## New merge request page
+You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue).
 
-On the **New merge request** page, start by filling in the title and description
-for the merge request. If commits already exist on the branch, GitLab suggests a
-merge request title for you:
+## When you add, edit, or upload a file
 
-- **If a multi-line commit message exists**: GitLab adds the first line of the
-  first multi-line commit message as the title. Any additional lines in that
-  commit message become the description.
-- **If no multi-line commit message exists**: GitLab adds the branch name as the
-  title, and leaves the description blank.
+You can create a merge request when you add, edit, or upload a file to a repository.
 
-The title is the only field that is mandatory in all cases.
+1. Add, edit, or upload a file to the repository.
+1. In the **Commit message**, enter a reason for the commit.
+1. Select the **Target branch** or create a new branch by typing the name (without spaces, capital letters, or special chars).
+1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only
+   if the target is not the same as the source branch, or if the source branch is protected.
+1. Select **Commit changes**.
 
-From there, you can fill it with information (title, description,
-assignee(s), milestone, labels, approvers) and click **Create merge request**.
+## When you create a branch
 
-From that initial screen, you can also see all the commits,
-pipelines, and file changes pushed to your branch before submitting
-the merge request.
+You can create a merge request when you create a branch.
 
-![New merge request page](img/new_merge_request_page_v12_6.png)
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left menu, select **Repository > Branches**.
+1. Type a branch name and select **New branch**.
+1. Above the file list, on the right side, select **Create merge request**.
+   A merge request is created. The default branch is the target.
+1. Fill out the fields and select **Create merge request**.
 
-NOTE:
-You can push one or more times to your branch in GitLab before
-creating the merge request.
+## When you use Git commands locally
 
-## Create merge request button
+You can create a merge request by running Git commands on your local machine.
 
-Once you have pushed a new branch to GitLab, visit your repository
-in GitLab and to see a call-to-action at the top of your screen
-from which you can click the button **Create merge request**.
+1. Create a branch:
 
-![Create merge request button](img/create_merge_request_button_v12_6.png)
+   ```shell
+   git checkout -b my-new-branch
+   ```
 
-You can also see the **Create merge request** button in the top-right of the:
+1. Create, edit, or delete files. The stage and commit them:
 
-- **Project** page.
-- **Repository > Files** page.
-- **Merge requests** page.
+   ```shell
+   git add .
+   git commit -m "My commit message"
+   ```
 
-In this case, GitLab uses the most recent branch you pushed
-changes to as the source branch, and the default branch in the current
-project as the target.
+1. [Push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom):
 
-## New merge request by adding, editing, and uploading a file
+   ```shell
+   git push origin my-new-branch
+   ```
 
-When you choose to edit, add, or upload a file through the GitLab UI,
-at the end of the file you see the option to add the **Commit message**,
-to select the **Target branch** of that commit, and the checkbox to
-**Start new a merge request with these changes**.
+   GitLab prompts you with a direct link for creating a merge request:
 
-Similarly, if you change files through the Web IDE, when you navigate to **Commit** on the left-hand sidebar, you see these same options.
+   ```plaintext
+   ...
+   remote: To create a merge request for docs-new-merge-request, visit:
+   remote:   https://gitlab.example.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch
+   ```
 
-Once you have added, edited, or uploaded the file:
+1. Copy the link and paste it in your browser.
 
-1. Describe your changes in the commit message.
-1. Select an existing branch to add your commit into, or, if you'd like to create a new branch, type the new branch name (without spaces, capital letters, or special chars).
-1. Keep the checkbox checked to start a new merge request straightaway, or, uncheck it to add more changes to that branch before starting the merge request.
-1. Click **Commit changes**.
+You can add other [flags to commands when pushing through the command line](../push_options.md)
+to reduce the need for editing merge requests manually through the UI.
 
-If you chose to start a merge request, you are taken to the
-[**New merge request** page](#new-merge-request-page), from
-which you can fill it in with information and submit the merge request.
+## When you work in a fork
 
-The merge request targets the default branch of the repository.
-If you want to change it, you can do it later by editing the merge request.
+You can create a merge request from your fork to contribute back to the main project.
 
-## New merge request from a new branch created through the UI
-
-To quickly start working on files through the GitLab UI,
-navigate to your project's **Repository > Branches** and click
-**New branch**. A new branch is created and you can start
-editing files.
-
-Once committed and pushed, you can click on the [**Create merge request**](#create-merge-request-button)
-button to open the [**New merge request** page](#new-merge-request-page).
-A new merge request is started using the current branch as the source,
-and the default branch in the current project as the target.
-
-## New merge request from your local environment
-
-Assuming you have your repository cloned into your computer and you'd
-like to start working on changes to files, start by creating and
-checking out a new branch:
-
-```shell
-git checkout -b my-new-branch
-```
-
-Work on your file changes, stage, and commit them:
+1. On the top bar, select **Menu > Project**.
+1. Select your fork of the repository.
+1. On the left menu, go to **Merge requests**, and select **New merge request**.
+1. In the **Source branch** drop-down list box, select the branch in your forked repository as the source branch.
+1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch.
+   You can set a [default target project](#set-the-default-target-project) to
+   change the default target branch (which can be useful if you are working in a
+   forked project).
+1. Select **Compare branches and continue**.
+1. Select **Submit merge request**.
 
-```shell
-git add .
-git commit -m "My commit message"
-```
+After your work is merged, if you don't intend to
+make any other contributions to the upstream project, you can unlink your
+fork from its upstream project. Go to **Settings > Advanced Settings** and
+[remove the forking relationship](../settings/index.md#removing-a-fork-relationship).
 
-Once you're done, [push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom):
+For more information, [see the forking workflow documentation](../repository/forking_workflow.md).
 
-```shell
-git push origin my-new-branch
-```
+## By sending an email **(FREE SELF)**
 
-In the output, GitLab prompts you with a direct link for creating
-a merge request:
+> 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.
 
-```shell
-...
-remote: To create a merge request for docs-new-merge-request, visit:
-remote:   https://gitlab-instance.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch
-```
+You can create a merge request by sending an email message to GitLab.
+The merge request target branch is the project's default branch.
 
-Copy that link and paste it in your browser, and the [**New merge request page**](#new-merge-request-page)
-is displayed.
+Prerequisites:
 
-There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI.
+- A GitLab administrator must configure [incoming email](../../../administration/incoming_email.md).
+- A GitLab administrator must configure [Reply by email](../../../administration/reply_by_email.md).
 
-If you didn't push your branch to GitLab through the command line
-(for example, you used a Git CLI application to push your changes),
-you can create a merge request through the GitLab UI by clicking
-the [**Create merge request**](#create-merge-request-button) button.
+To create a merge request by sending an email:
 
-## New merge request from an issue
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left menu, select **Merge requests**.
+1. In the top right, select **Email a new merge request to this project**.
+   An email address is displayed. Copy this address.
+   Ensure you keep this address private.
+1. Open an email and compose a message with the following information:
 
-You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue).
+   - The **To** line is the email address you copied.
+   - The subject line is the source branch name.
+   - The message body is the merge request description.
 
-## New merge request from the merge requests page
+1. Send the email message.
 
-You can start creating a new merge request by clicking the
-**New merge request** button on the **merge requests** page in a project.
-Then 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
-[**New merge request** page](#new-merge-request-page) and fill in the details.
+A merge request is created.
 
-## New merge request from a fork
+### Add attachments when creating a merge request by email
 
-After forking a project and applying your local changes, complete the following steps to
-create a merge request from your fork to contribute back to the main project:
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5.
 
-1. On the top bar, select **Menu > Project**.
-1. Select **Your Projects**, then select your fork of the repository.
-1. In the left menu, go to **Merge requests**, and click **New merge request**.
-1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch.
-1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch.
-   You can set a [default target project](#set-the-default-target-project) to
-   change the default target branch (which can be useful when working with a
-   forked project).
-1. After entering the credentials, click **Compare branches and continue** to compare your local changes to the upstream repository.
-1. Assign a user to review your changes, and click **Submit merge request**.
+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
+ordered by name.
 
-When the changes are merged, your changes are added to the upstream repository and
-the branch as per specification. After your work is merged, if you don't intend to
-make any other contributions to the upstream project, you can unlink your
-fork from its upstream project in the **Settings > Advanced Settings** section by
-[removing the forking relationship](../settings/index.md#removing-a-fork-relationship).
+The combined size of the patches can be 2 MB.
 
-For further details, [see the forking workflow documentation](../repository/forking_workflow.md).
+If the source branch from the subject does not exist, it is
+created from the repository's HEAD or the specified target branch.
+You can specify the target branch by using the
+[`/target_branch` quick action](../quick_actions.md). If the source
+branch already exists, the patches are applied on top of it.
 
 ## Set the default target project
 
-Merge requests have a source and a target project which are the same, unless
+Merge requests have a source and a target project that are the same, unless
 forking is involved. Creating a fork of the project can cause either of these
 scenarios when you create a new merge request:
 
@@ -197,57 +163,11 @@ scenarios when you create a new merge request:
   option).
 - You target your own fork.
 
-If you want to have merge requests from a fork by default target your own fork
-(instead of the upstream project), you can change the default by:
+To have merge requests from a fork by default target your own fork
+(instead of the upstream project), you can change the default.
 
-1. In your project, go to **Settings > General > Merge requests**.
+1. On the top bar, select **Menu > Project**.
+1. On the left menu, select **Settings > General > Merge requests**.
 1. In the **Target project** section, select the option you want to use for
    your default target project.
 1. Select **Save changes**.
-
-## New merge request by email **(FREE SELF)**
-
-_This feature needs [incoming email](../../../administration/incoming_email.md)
-to be configured by a GitLab administrator to be available._ It isn't
-available in 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 is
-used as the source branch name for the new merge request and the target branch
-is the default branch for the project. The message body (if not empty)
-is 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 has 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 email
-
-> [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` are considered patches and they are processed
-ordered by name.
-
-The combined size of the patches can be 2MB.
-
-If the source branch from the subject does not exist, it is
-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 are applied on top of it.
-
-## Reviewing and managing merge requests
-
-Once you have submitted a merge request, it can be [reviewed and managed](reviews/index.md) through GitLab.