From 04fb20c5bb16b1cc273d46ede018a70b2efe47c9 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Tue, 12 Dec 2023 13:59:06 -0800 Subject: [PATCH 1/7] Finish fact-checking the create-MR page Process the remaining few subheadings for "create a merge request" for accuracy. --- .../merge_requests/creating_merge_requests.md | 88 +++++++++---------- 1 file changed, 40 insertions(+), 48 deletions(-) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 951c848dee1d17..c09ff23f9dac98 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -155,23 +155,34 @@ You can create a merge request by running Git commands on your local machine. You can create a merge request from your fork to contribute back to the main project. -1. On the left sidebar, select **Search or go to** and find your project. -1. Select your fork of the repository. -1. On the left sidebar, select **Code > Merge requests**, and select **New merge request**. -1. In the **Source branch** dropdown list box, select the branch in your forked repository as the source branch. -1. In the **Target branch** dropdown 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. On the left sidebar, select **Search or go to** and find your fork. +1. Select **Code > Merge requests**, and select **New merge request**. +1. For **Source branch**, select the branch in your fork that contains your changes. +1. For **Target branch**, select a branch from the upstream repository. + + NOTE: + If you contribute changes upstream frequently, consider setting a + [default target project](#set-the-default-target-project) for your fork. + 1. Select **Compare branches and continue**. 1. Select **Create merge request**. -After your work is merged, if you don't intend to -make any other contributions to the upstream project, you can -[unlink your fork](../repository/forking_workflow.md#unlink-a-fork) from its upstream project. +After your work merges, [unlink your fork](../repository/forking_workflow.md#unlink-a-fork) +from its upstream project if you don't intend to make more contributions.. For more information, [see the forking workflow documentation](../repository/forking_workflow.md). +### Set the default target project + +By default, merge requests originating from a fork target the _upstream_ project. +To set your fork as the default target instead, change the default target: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > Merge requests**. +1. In the **Target project** section, select the option you want to use for + your default target project. +1. Select **Save changes**. + ## By sending an email You can create a merge request by sending an email message to GitLab. @@ -186,53 +197,34 @@ To create a merge request by sending an email: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. -1. In the upper-right corner, select **Email a new merge request to this project**. - An email address is displayed. Copy this address. - Ensure you keep this address private. +1. If you're creating the first merge request from this fork: + - TODO +1. If you've created merge requests from this fork before, select **Email a new merge request to this project**. +1. In the dialog, copy the email address shown. Keep this address private. Anyone who + has it can create issues or merge requests as if they were you. 1. Open an email and compose a message with the following information: - 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. + - The **Subject** is the source branch name. + - The body of the email is the merge request description. -1. Send the email message. +1. To add commits, attach `.patch` files to the message. +1. Send the email. A merge request is created. ### Add attachments when creating a merge request by email -You can add commits to a merge request by adding -patches as attachments to the email. All attachments with a file name ending in `.patch` are considered patches and are processed -ordered by name. - -The combined size of the patches can be 2 MB. +Add commits to a merge request by adding patches as attachments to the email. -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 - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58093) in GitLab 13.11. - -Merge requests have a source and a target project that are the same, unless -forking is involved. Creating a fork of the project can cause either of these -scenarios when you create a new merge request: - -- You target an upstream project (the project you forked, and the default - option). -- You target your own fork. - -To have merge requests from a fork by default target your own fork -(instead of the upstream project), you can change the default. - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > Merge requests**. -1. In the **Target project** section, select the option you want to use for - your default target project. -1. Select **Save changes**. +- The combined size of the patches must be 2 MB or less. +- To be considered a patch, the attachment's file name must end in `.patch`. +- Patches are processed in order by name. +- If the source branch from the subject does not exist, it is + created from the repository's `HEAD`, or the default target branch. + To change the target branch manually, use the + [`/target_branch` quick action](../quick_actions.md). +- If the source branch already exists, patches are applied on top of it. ## Troubleshooting -- GitLab From 1563719cfe9f05f760ec1e5f82261abdd64bd8c5 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 22 Dec 2023 15:00:43 -0800 Subject: [PATCH 2/7] Add prerequisites for setting default project Based on Stas' explanation of how to make the setting appear. --- .../merge_requests/creating_merge_requests.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index c09ff23f9dac98..51e3daeb1614f4 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -175,7 +175,17 @@ For more information, [see the forking workflow documentation](../repository/for ### Set the default target project By default, merge requests originating from a fork target the _upstream_ project. -To set your fork as the default target instead, change the default target: +To set your fork as the default target instead, change the default target. + +Prerequisites: + +- You're working in a fork. +- The upstream project allows merge requests to be created. +- The [visibility settings](../../public_access.md#change-project-visibility) for + the fork must match, or be less strict than, the upstream repository. For example: + this setting isn't shown if your fork is private, but the upstream is public. + +To do this: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. -- GitLab From 3d460d212218b544b76da8abb23906fa83bb5272 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 22 Dec 2023 15:04:27 -0800 Subject: [PATCH 3/7] Clarify where the MR is created It gets made in the target project, not in the fork. --- doc/user/project/merge_requests/creating_merge_requests.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 51e3daeb1614f4..0af8c31f028124 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -165,10 +165,11 @@ You can create a merge request from your fork to contribute back to the main pro [default target project](#set-the-default-target-project) for your fork. 1. Select **Compare branches and continue**. -1. Select **Create merge request**. +1. Select **Create merge request**. The merge request is created in the target project, + not your fork. After your work merges, [unlink your fork](../repository/forking_workflow.md#unlink-a-fork) -from its upstream project if you don't intend to make more contributions.. +from its upstream project if you don't intend to make more contributions. For more information, [see the forking workflow documentation](../repository/forking_workflow.md). @@ -180,6 +181,7 @@ To set your fork as the default target instead, change the default target. Prerequisites: - You're working in a fork. +- You must have at least the Developer role, or be allowed to create merge requests in the project. - The upstream project allows merge requests to be created. - The [visibility settings](../../public_access.md#change-project-visibility) for the fork must match, or be less strict than, the upstream repository. For example: @@ -202,6 +204,7 @@ Prerequisites: - A GitLab administrator must configure [incoming email](../../../administration/incoming_email.md). - A GitLab administrator must configure [Reply by email](../../../administration/reply_by_email.md). +- You must have at least the Developer role, or be allowed to create merge requests in the project. To create a merge request by sending an email: -- GitLab From 795e53a1bc736116db34235aea0b559cccd9e3e1 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 22 Dec 2023 15:07:44 -0800 Subject: [PATCH 4/7] Correct error for default target of forks This was backwards in the docs. Let's correct it. By default, forks target themselves. --- doc/user/project/merge_requests/creating_merge_requests.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 0af8c31f028124..87d113425dec12 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -175,8 +175,9 @@ For more information, [see the forking workflow documentation](../repository/for ### Set the default target project -By default, merge requests originating from a fork target the _upstream_ project. -To set your fork as the default target instead, change the default target. +By default, merge requests originating from a fork target your fork, not the upstream project. +If you frequently contribute back to the upstream project, and want to target it +by default, change the default target for your fork. Prerequisites: -- GitLab From 32de5650abe846be42d014ded99bb5954683852d Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 22 Dec 2023 15:19:18 -0800 Subject: [PATCH 5/7] Add troubleshooting for email failure Use the error message the engineer provided to build a small troubleshooting item for when MR-by-email fails. --- .../merge_requests/creating_merge_requests.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 87d113425dec12..3c4bfe560b35f0 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -203,6 +203,7 @@ The merge request target branch is the project's default branch. Prerequisites: +- The merge request must target the current project, not an upstream project. - A GitLab administrator must configure [incoming email](../../../administration/incoming_email.md). - A GitLab administrator must configure [Reply by email](../../../administration/reply_by_email.md). - You must have at least the Developer role, or be allowed to create merge requests in the project. @@ -255,3 +256,14 @@ To make this button appear, one possible workaround is to [remove your project's fork relationship](../repository/forking_workflow.md#unlink-a-fork). After removal, the fork relationship cannot be restored. This project can no longer be able to receive or send merge requests to the source project, or other forks. + +### Email message could not be processed + +When sending an email to create a merge request, and you attempt to target an +upstream project, GitLab responds with this error: + +```plaintext +Unfortunately, your email message to GitLab could not be processed. + +You are not allowed to perform this action. If you believe this is in error, contact a staff member. +``` -- GitLab From dadf5aca0a952177116c75bf05f915264d32ec39 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 22 Dec 2023 15:29:36 -0800 Subject: [PATCH 6/7] Make super clear to select the upstream It's very easy to skip this one step, and leave this setting pointed at your fork. Call it out in two separate steps, rather than blending them together into one step. --- doc/user/project/merge_requests/creating_merge_requests.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 3c4bfe560b35f0..8e747d2158bf5c 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -158,7 +158,10 @@ You can create a merge request from your fork to contribute back to the main pro 1. On the left sidebar, select **Search or go to** and find your fork. 1. Select **Code > Merge requests**, and select **New merge request**. 1. For **Source branch**, select the branch in your fork that contains your changes. -1. For **Target branch**, select a branch from the upstream repository. +1. For **Target branch**: + + 1. Select the target project. (Make sure to select the upstream project, rather than your fork.) + 1. Select a branch from the upstream repository. NOTE: If you contribute changes upstream frequently, consider setting a -- GitLab From 6181f3e429741850319925b18a8751aab7e5df82 Mon Sep 17 00:00:00 2001 From: Stanislav Lashmanov Date: Tue, 26 Dec 2023 02:00:49 +0000 Subject: [PATCH 7/7] Remove any fork mentions from the MR creation via email section --- doc/user/project/merge_requests/creating_merge_requests.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 8e747d2158bf5c..d2c5b0af339565 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -215,9 +215,7 @@ To create a merge request by sending an email: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. -1. If you're creating the first merge request from this fork: - - TODO -1. If you've created merge requests from this fork before, select **Email a new merge request to this project**. +1. If the project contains any merge requests, select **Email a new merge request to this project**. 1. In the dialog, copy the email address shown. Keep this address private. Anyone who has it can create issues or merge requests as if they were you. 1. Open an email and compose a message with the following information: -- GitLab