diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index e83789efdbfb4e8b6357520a4f496036f261602b..72603ed94c063f0db84c5833d4dc5bafa2021efe 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -32,7 +32,7 @@ can still be successfully merged into the target. When the merge request can't be merged, the pipeline runs against the source branch only. For example, when: - The target branch has changes that conflict with the changes in the source branch. -- The merge request is a [**Draft** merge request](../../../user/project/merge_requests/work_in_progress_merge_requests.md). +- The merge request is a [**Draft** merge request](../../../user/project/merge_requests/drafts.md). In these cases, the pipeline runs as a [pipeline for merge requests](../index.md) and is labeled as `detached`. If these cases no longer exist, new pipelines diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index d02573a0e065bc70e3ccb1a80840bdbbabdbafee..c238951be51adce99600d2b0fd367b00102eb629 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -187,7 +187,7 @@ The name of a branch might be dictated by organizational standards. When you are done or want to discuss the code, open a merge request. A merge request is an online place to discuss the change and review the code. -If you open the merge request but do not assign it to anyone, it is a [draft merge request](../user/project/merge_requests/work_in_progress_merge_requests.md). +If you open the merge request but do not assign it to anyone, it is a [draft merge request](../user/project/merge_requests/drafts.md). These are used to discuss the proposed implementation but are not ready for inclusion in the `master` branch yet. Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to prevent it from being merged before it's ready. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index c3adce338265c35ecea4f9042b1dfaecedf12dac..baf0867189464c6d1c6fa9955849b037f46c4bf6 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -249,7 +249,7 @@ Also: ### Create Merge Request -Create a new branch and [**Draft** merge request](../merge_requests/work_in_progress_merge_requests.md) +Create a new branch and [**Draft** merge request](../merge_requests/drafts.md) in one action. The branch is named `issuenumber-title` by default, but you can choose any name, and GitLab verifies that it is not already in use. The merge request inherits the milestone and labels of the issue, and is set to automatically diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md new file mode 100644 index 0000000000000000000000000000000000000000..522fef0be71c0df3750c3e9ee8e0d739bee6c551 --- /dev/null +++ b/doc/user/project/merge_requests/drafts.md @@ -0,0 +1,95 @@ +--- +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 +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/work_in_progress_merge_requests.html' +--- + +# Draft merge requests **(FREE)** + +If a merge request isn't ready to merge, potentially because of continued development +or open threads, you can prevent it from being accepted before you +[mark it as ready](#mark-merge-requests-as-ready). Flag it as a draft to disable +the **Merge** button until you remove the **Draft** flag: + + + +## Mark merge requests as drafts + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. +> - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. + +There are several ways to flag a merge request as a draft: + +- **Viewing a merge request**: In the top right corner of the merge request, click **Mark as draft**. +- **Creating or editing a merge request**: Add `[Draft]`, `Draft:` or `(Draft)` to + the beginning of the merge request's title, or click **Start the title with Draft:** + below the **Title** field. +- **Commenting in an existing merge request**: Add the `/draft` + [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) + in a comment. This quick action is a toggle, and can be repeated to change the status + again. This quick action discards any other text in the comment. +- **Creating a commit**: Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the + beginning of a commit message targeting the merge request's source branch. This + is not a toggle, and adding this text again in a later commit doesn't mark the + merge request as ready. + +WARNING: +Adding `WIP:` to the start of the merge request's title still marks a merge request +as a draft. This feature is scheduled for removal in GitLab 14.0. Use `Draft:` instead. + +## Mark merge requests as ready + +When a merge request is ready to be merged, you can remove the `Draft` flag in several ways: + +- **Viewing a merge request**: In the top right corner of the merge request, click **Mark as ready**. + Users with [Developer or greater permissions](../../permissions.md) + can also scroll to the bottom of the merge request description and click **Mark as ready**: + +  + +- **Editing an existing merge request**: Remove `[Draft]`, `Draft:` or `(Draft)` + from the beginning of the title, or click **Remove the Draft: prefix from the title** + below the **Title** field. +- **Commenting in an existing merge request**: Add the `/draft` + [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) + in a comment in the merge request. This quick action is a toggle, and can be repeated + to change the status back. This quick action discards any other text in the comment. + +## Include or exclude drafts when searching + +When viewing or searching in your project's merge requests list, you can include or exclude +draft merge requests: + +1. In your project, select **Merge Requests** from the left sidebar. +1. In the navigation bar, click **Open**, **Merged**, **Closed**, or **All** to + filter by merge request status. +1. Click the search box to display a list of filters and select **Draft**, or + enter the word `draft`. +1. Select `=`. +1. Select **Yes** to include drafts, or **No** to exclude, and press **Return** + to update the list of merge requests: + +  + +## Pipelines for drafts + +When the [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) +feature is enabled, draft merge requests run +[merge request pipelines](../../../ci/merge_request_pipelines/index.md) only. + +To run pipelines for merged results, you must +[mark the merge request as ready](#mark-merge-requests-as-ready). + +<!-- ## 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/getting_started.md b/doc/user/project/merge_requests/getting_started.md index dc6c5cdbfe679713666c548b1d7f389d855dbc6c..61eb742e42f157a27f001ed8dec89676cdd9476a 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -60,7 +60,7 @@ request's page at the top-right side: - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. -- Set the merge request as a [**Draft**](work_in_progress_merge_requests.md) to avoid accidental merges before it is ready. +- Set the merge request as a [**Draft**](drafts.md) to avoid accidental merges before it is ready. After you have created the merge request, you can also: diff --git a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png new file mode 100644 index 0000000000000000000000000000000000000000..3bac9f7fee876cf2d70d67a42535dcfcbf849a1e Binary files /dev/null and b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_10.png differ diff --git a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png b/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png deleted file mode 100644 index f79687725008a5e2f9610e4806286f8f16d5734c..0000000000000000000000000000000000000000 Binary files a/doc/user/project/merge_requests/img/draft_blocked_merge_button_v13_2.png and /dev/null differ diff --git a/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png new file mode 100644 index 0000000000000000000000000000000000000000..4458df987d6be65d90416bfde8b22f1ba76efd9d Binary files /dev/null and b/doc/user/project/merge_requests/img/filter_draft_merge_requests_v13_10.png differ diff --git a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png deleted file mode 100644 index 0989b41e2a46583f04c124c0eba1c588bc9774c6..0000000000000000000000000000000000000000 Binary files a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png and /dev/null differ diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 1949677177e3d58d90ce8d6894fbf1b38b19b3c8..2e6b7c33f343d7fcfae8d00c0fb602cad7428412 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -40,8 +40,7 @@ require changes to `awesome-lib`, and so necessitate two merge requests. Merging the `awesome-project` merge request before the `awesome-lib` one would break the `master`branch. -The `awesome-project` merge request could be [marked as -**Draft**](work_in_progress_merge_requests.md), +The `awesome-project` merge request could be [marked as **Draft**](drafts.md), and the reason for the draft stated included in the comments. However, this requires the state of the `awesome-lib` merge request to be manually tracked, and doesn't scale well if the `awesome-project` merge request diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 6eef6505b5d44cdf96443fea7d372cbd3776c9f9..4b854da116e0b7b38ed04023e4767c31b7cceeb2 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -1,78 +1,8 @@ --- -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 +redirect_to: 'drafts.md' --- -# Draft merge requests **(FREE)** +This document was moved to [another location](drafts.md). -If a merge request is not yet ready to be merged, perhaps due to continued development -or open threads, you can prevent it from being accepted before it's ready by flagging -it as a **Draft**. This disables the **Merge** button, preventing it from -being merged. It stays disabled until the **Draft** flag has been removed. - - - -When [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) -is enabled, draft merge requests run [merge request pipelines](../../../ci/merge_request_pipelines/index.md) -only. - -To run pipelines for merged results, you must [remove the draft status](#removing-the-draft-flag-from-a-merge-request). - -## Adding the "Draft" flag to a merge request - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. -> - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. - -There are several ways to flag a merge request as a Draft: - -- Click the **Mark as draft** button on the top-right corner of the merge request's page. -- Add `[Draft]`, `Draft:` or `(Draft)` to the start of the merge request's title. Clicking on - **Start the title with Draft:**, under the title box, when editing the merge request's - description has the same effect. -- **Deprecated** Add `[WIP]` or `WIP:` to the start of the merge request's title. - **WIP** still works but was deprecated in favor of **Draft**. It is scheduled for removal in the next major version (GitLab 14.0). -- Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) - in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment is discarded. -- Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the - merge request's source branch. This is not a toggle, and doing it again in another - commit has no effect. - -## Removing the "Draft" flag from a merge request - -Similar to above, when a Merge Request is ready to be merged, you can remove the -`Draft` flag in several ways: - -- Click the **Mark as ready** button on the top-right corner of the merge request's page. -- Remove `[Draft]`, `Draft:` or `(Draft)` from the start of the merge request's title. Clicking on - **Remove the Draft: prefix from the title**, under the title box, when editing the merge - request's description, has the same effect. -- Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) - in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment is discarded. -- Click on the **Resolve Draft status** button near the bottom of the merge request description, - next to the **Merge** button (see [image above](#draft-merge-requests)). - Must have at least Developer level permissions on the project for the button to - be visible. - -## Including/excluding WIP merge requests when searching - -When viewing/searching the merge requests list, you can choose to include or exclude -WIP merge requests. Add a **WIP** filter in the search box, and choose **Yes** -to include, or **No** to exclude. - - - -<!-- ## 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. --> +<!-- This redirect file can be deleted after <2021-05-19>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->