From 9e858de543879d5b8fa33b71d97c31217e00615a Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 8 Dec 2023 11:32:46 -0800 Subject: [PATCH 1/6] Begin updating the content of the create-MR page I'm not the entire way through the page, but I'm losing steam and we can get value from the updates I've done so far. This commit steps through the first few subheadings on this page, checking each step of each process, and updating them to match current expectations. --- .../merge_requests/creating_merge_requests.md | 110 +++++++++++------- 1 file changed, 69 insertions(+), 41 deletions(-) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 723bda0e02c4fb..9815c560d43552 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -20,65 +20,73 @@ to streamline merge request creation. You can create a merge request from the list of merge requests. 1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Code > Merge requests**. +1. Select **Merge requests**. 1. In the upper-right corner, 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**. +1. Select a source and target branch, then select **Compare branches and continue**. +1. Fill out the fields on the **New merge request** page, then select **Create merge request**. -NOTE: -Merge requests are designed around a one-to-one (1:1) branch relationship. Only one open merge request may -be associated with a given target branch at a time. +Each branch can be associated with only one open merge request. If a merge request +already exists for this branch, a link to the existing merge request is shown. ## From an issue -> The **Create merge request** button [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. +> Selecting **Create merge request** [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. After merging the merge request, the issue is closed automatically, unless -[automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). -You can see a **Create merge request** dropdown list below the issue description. +[automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing): -NOTE: -In GitLab 14.8 and later, selecting **Create merge request** -[redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) -instead of immediately creating the merge request. +::Tabs -**Create merge request** doesn't display if: +:::TabTitle Merge request and branch -- A branch with the same name already exists. -- A merge request already exists for this branch. -- Your project has an active fork relationship. -- Your project is private and the issue is confidential. +To create a branch and a merge request at the same time: -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. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Issues** and find your issue. +1. Go to the bottom of the issue description. +1. Select **Create merge request > Create merge request and branch**. +1. In the dialog, review the suggested branch name. It's based on your project's + [branch name template](../repository/branches/index.md) Rename it if the + branch name is already taken, or you need a different branch name. +1. Select a source branch or tag. +1. Select **Create merge request**. + +:::TabTitle Branch only -The dropdown list contains the options **Create merge request and branch** and **Create branch**. +To create only a branch directly from an issue: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Issues** and find your issue. +1. Go to the bottom of the issue description. +1. Select **Create merge request > Create branch**. +1. In the dialog, review the suggested branch name. It's based on your project's + [branch name template](../repository/branches/index.md) Rename it if the + branch name is already taken, or you need a different branch name. +1. Select a source branch or tag. +1. Select **Create branch**. -After selecting one of these options, a new branch or branch and merge request -is created based on your project's [default branch](../repository/branches/default.md). -The branch name is based on your project's [branch name template](../repository/branches/index.md), -but this value can be changed. +::EndTabs -When you select **Create branch** in an empty -repository project, GitLab performs these actions: +If your Git repository is empty, GitLab: - Creates a default branch. - Commits a blank `README.md` file to it. - Creates and redirects you to a new branch based on the issue title. -- _If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes,_ +- If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes, GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) by helping you create a `.gitlab-ci.yml` file. -After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly-created branch, -the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) -`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the -merge request is merged. +If the name of the branch you create is +[prefixed with the issue number](../repository/branches/index.md#prefix-branch-names-with-issue-numbers), +GitLab cross-links the issue and merge request, and adds the +[issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) +to the description of the merge request. In most cases, this looks like `Closes #ID`, +where `ID` is the ID of the issue. If your project is configured with a +[closing pattern](../issues/managing_issues.md#default-closing-pattern), the issue closes +when the merge request merges. ## When you add, edit, or upload a file @@ -112,20 +120,27 @@ You can create a merge request by running Git commands on your local machine. git checkout -b my-new-branch ``` -1. Create, edit, or delete files. The stage and commit them: +1. Create, edit, or delete files as needed. + +1. Mark the files as ready to commit (staging them) and commit them locally: ```shell + # Mark the files as ready to commit git add . + # Commit the changes locally git commit -m "My commit message" ``` -1. [Push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlab): +1. [Push your branch and its commits to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlab): ```shell git push origin my-new-branch ``` - GitLab prompts you with a direct link for creating a merge request: + To reduce the number of fields to edit later in the merge request, use + [push options](../push_options.md) to set the value of fields. + +1. In the response to the `git push`, GitLab provides a direct link to create the merge request: ```plaintext ... @@ -135,9 +150,6 @@ You can create a merge request by running Git commands on your local machine. 1. Copy the link and paste it in your browser. -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. - ## When you work in a fork You can create a merge request from your fork to contribute back to the main project. @@ -220,3 +232,19 @@ To have merge requests from a fork by default target your own fork 1. In the **Target project** section, select the option you want to use for your default target project. 1. Select **Save changes**. + +## Troubleshooting + +### No option to create a merge request on an issue + +The option to **Create merge request** doesn't display on an issue if: + +- A branch with the same name already exists. +- A merge request already exists for this branch. +- Your project has an active fork relationship. +- Your project is private and the issue is confidential. + +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. -- GitLab From 1acd9352861318c1256e1cb4c90c90f75c270658 Mon Sep 17 00:00:00 2001 From: Amy Qualls Date: Fri, 8 Dec 2023 12:27:21 -0800 Subject: [PATCH 2/6] Test and update steps for MR-from-upload Correct another set of steps. --- 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 9815c560d43552..e62032d079b0f4 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -94,10 +94,11 @@ You can create a merge request when you add, edit, or upload a file to a reposit 1. [Add, edit, or upload](../repository/web_editor.md) 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). +1. Select the **Target branch** or create a new branch by typing the name. 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**. +1. Select **Upload file**. +1. Fill out the fields and select **Create merge request**. ## When you create a branch -- GitLab From 959a92c82aa2afbec1da5d556d2c94eee90bde13 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Mon, 11 Dec 2023 17:03:30 +0000 Subject: [PATCH 3/6] Apply 1 suggestion(s) to 1 file(s) --- doc/user/project/merge_requests/creating_merge_requests.md | 2 +- 1 file changed, 1 insertion(+), 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 e62032d079b0f4..713457e570dc8b 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -23,7 +23,7 @@ You can create a merge request from the list of merge requests. 1. Select **Merge requests**. 1. In the upper-right corner, select **New merge request**. 1. Select a source and target branch, then select **Compare branches and continue**. -1. Fill out the fields on the **New merge request** page, then select **Create merge request**. +1. Complete the fields on the **New merge request** page, then select **Create merge request**. Each branch can be associated with only one open merge request. If a merge request already exists for this branch, a link to the existing merge request is shown. -- GitLab From 1bac212c6aed688d2e7a49a42f0ded50db9bce6e Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Mon, 11 Dec 2023 17:07:35 +0000 Subject: [PATCH 4/6] Apply 1 suggestion(s) to 1 file(s) --- doc/user/project/merge_requests/creating_merge_requests.md | 2 +- 1 file changed, 1 insertion(+), 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 713457e570dc8b..0f93c2ce810542 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -30,7 +30,7 @@ already exists for this branch, a link to the existing merge request is shown. ## From an issue -> Selecting **Create merge request** [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) the behavior of the **Create merge request** button to open the merge request creation form in GitLab 14.8. If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. -- GitLab From da278d3bfbdce722314e6f6c12274f56b7a21113 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Mon, 11 Dec 2023 17:49:35 +0000 Subject: [PATCH 5/6] Apply 1 suggestion(s) to 1 file(s) --- doc/user/project/merge_requests/creating_merge_requests.md | 2 +- 1 file changed, 1 insertion(+), 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 0f93c2ce810542..b147daef9696c5 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -20,7 +20,7 @@ to streamline merge request creation. You can create a merge request from the list of merge requests. 1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Merge requests**. +1. Select **Code > Merge requests**. 1. In the upper-right corner, select **New merge request**. 1. Select a source and target branch, then select **Compare branches and continue**. 1. Complete the fields on the **New merge request** page, then select **Create merge request**. -- GitLab From 9121eab20712ddd21be2ed15175a3d3475cb3755 Mon Sep 17 00:00:00 2001 From: Marcin Sedlak-Jakubowski Date: Mon, 11 Dec 2023 18:21:42 +0000 Subject: [PATCH 6/6] Fix path to issue list --- doc/user/project/merge_requests/creating_merge_requests.md | 2 +- 1 file changed, 1 insertion(+), 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 b147daef9696c5..85874692725a95 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -59,7 +59,7 @@ To create a branch and a merge request at the same time: To create only a branch directly from an issue: 1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Issues** and find your issue. +1. Select **Plan > Issues** and find your issue. 1. Go to the bottom of the issue description. 1. Select **Create merge request > Create branch**. 1. In the dialog, review the suggested branch name. It's based on your project's -- GitLab