From 6dfcceb962f2281ff9108791543192a4a3d149f7 Mon Sep 17 00:00:00 2001
From: Amy Qualls <aqualls@gitlab.com>
Date: Tue, 23 Aug 2022 06:22:15 +0000
Subject: [PATCH] Rename long page to dependencies.md
There's no need for this page to be this long. Let's make it less
painful for users.
---
doc/development/code_review.md | 8 +-
.../project/merge_requests/dependencies.md | 163 +++++++++++++++++
.../project/merge_requests/getting_started.md | 2 +-
.../merge_request_dependencies.md | 166 +-----------------
4 files changed, 175 insertions(+), 164 deletions(-)
create mode 100644 doc/user/project/merge_requests/dependencies.md
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index ec3e8220845eb..8319a717a7cb3 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -125,7 +125,7 @@ As an experiment, we want to introduce a `local` reviewer status for database re
focusing on work from a team/stage, but not outside of it. This helps to focus and build great domain
knowledge. We are not introducing changes to the reviewer roulette till we evaluate the impact and feedback from this
experiment. We ask to respect reviewers who decline reviews based on their focus on `local` reviews. For tracking purposes,
-please use in your personal YAML file entry: `- reviewer database local` instead of `- reviewer database`.
+please use in your personal YAML file entry: `- reviewer database local` instead of `- reviewer database`.
### Approval guidelines
@@ -330,7 +330,7 @@ Maintainers are the DRI of assuring that the acceptance criteria of a merge requ
In general, [quality is everyone’s responsibility](https://about.gitlab.com/handbook/engineering/quality/),
but maintainers of an MR are held responsible for **ensuring** that an MR meets those general quality standards.
-If a maintainer feels that an MR is substantial enough, or requires a [domain expert](#domain-experts),
+If a maintainer feels that an MR is substantial enough, or requires a [domain expert](#domain-experts),
maintainers have the discretion to request a review from another reviewer, or maintainer. Here are some
examples of maintainers proactively doing this during review:
@@ -419,7 +419,7 @@ first time.
codebase. Thorough descriptions help all reviewers understand your request
and test effectively.
- If you know your change depends on another being merged first, note it in the
- description and set a [merge request dependency](../user/project/merge_requests/merge_request_dependencies.md).
+ description and set a [merge request dependency](../user/project/merge_requests/dependencies.md).
- Be grateful for the reviewer's suggestions. ("Good call. I'll make that change.")
- Don't take it personally. The review is of the code, not of you.
- Explain why the code exists. ("It's like that because of these reasons. Would
@@ -490,7 +490,7 @@ experience, refactors the existing code). Then:
optionally resolve within the merge request or follow-up at a later stage.
- There's a [Chrome/Firefox add-on](https://gitlab.com/conventionalcomments/conventional-comments-button) which you can use to apply [Conventional Comment](https://conventionalcomments.org/) prefixes.
- Ensure there are no open dependencies. Check [linked issues](../user/project/issues/related_issues.md) for blockers. Clarify with the authors
-if necessary. If blocked by one or more open MRs, set an [MR dependency](../user/project/merge_requests/merge_request_dependencies.md).
+if necessary. If blocked by one or more open MRs, set an [MR dependency](../user/project/merge_requests/dependencies.md).
- After a round of line notes, it can be helpful to post a summary note such as
"Looks good to me", or "Just a couple things to address."
- Let the author know if changes are required following your review.
diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md
new file mode 100644
index 0000000000000..0c4815544011d
--- /dev/null
+++ b/doc/user/project/merge_requests/dependencies.md
@@ -0,0 +1,163 @@
+---
+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
+---
+
+# Merge request dependencies **(PREMIUM)**
+
+A single feature can span several merge requests, spread out across multiple projects,
+and the order in which the work merges can be significant. Use merge request dependencies
+when it's important to merge work in a specific order. Some examples:
+
+- Ensure changes to a required library are merged before changes to a project that
+ imports the library.
+- Prevent a documentation-only merge request from merging before the feature work
+ is itself merged.
+- Require a merge request updating a permissions matrix to merge, before merging work
+ from someone who hasn't yet been granted permissions.
+
+If your project `me/myexample` imports a library from `myfriend/library`,
+you might want to update your project to use a new feature in `myfriend/library`.
+However, if you merge changes to your project before the external library adds the
+new feature, you would break the default branch in your project. A merge request
+dependency prevents your work from merging too soon:
+
+```mermaid
+graph TB
+ A['me/myexample' project]
+ B['myfriend/library' project]
+ C[Merge request #1:<br>Create new version 2.5]
+ D[Merge request #2:<br>Add version 2.5<br>to build]
+ A-->|contains| D
+ B---->|contains| C
+ D-.->|depends on| C
+ C-.->|blocks| D
+```
+
+You could mark your `me/myexample` merge request as a [draft](drafts.md)
+and explain why in the comments. However, this approach is manual and does not scale, especially
+if your merge request relies on several others in multiple projects. Instead,
+use the draft (or ready) state to track the readiness of an individual
+merge request, and a merge request dependency to enforce merge order.
+
+NOTE:
+Merge request dependencies are a **PREMIUM** feature, but this restriction is
+enforced only for the dependent merge request. A merge request in a **PREMIUM**
+project can depend on a merge request in a **FREE** project, but a merge request
+in a **FREE** project cannot be marked as dependent.
+
+## View dependencies for a merge request
+
+If a merge request is dependent on another, the merge request reports section shows
+information about the dependency:
+
+
+
+To view dependency information on a merge request:
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Merge requests** and identify your merge request.
+1. Scroll to the merge request reports area. Dependent merge requests display information
+ about the total number of dependencies set, such as
+ **(status-warning)** **Depends on 1 merge request being merged**.
+1. Select **Expand** to view the title, milestone, assignee, and pipeline status
+ of each dependency.
+
+Until your merge request's dependencies all merge, your merge request
+cannot be merged. The message
+**Merge blocked: you can only merge after the above items are resolved** displays.
+
+### Closed merge requests
+
+Closed merge requests still prevent their dependents from being merged, because
+a merge request can close regardless of whether or not the planned work actually merged.
+
+If a merge request closes and the dependency is no longer relevant,
+remove it as a dependency to unblock the dependent merge request.
+
+## Create a new dependent merge request
+
+When you create a new merge request, you can prevent it from merging until after
+other specific work merges, even if the merge request is in a different project.
+
+Prerequisites:
+
+- You must have at least the Developer role or be allowed to create merge requests in the project.
+- The dependent merge request must be in a project in a **PREMIUM** or higher tier.
+
+To create a new merge request and mark it as dependent on another:
+
+1. [Create a new merge request](creating_merge_requests.md).
+1. In **Merge request dependencies**, paste either the reference or the full URL
+ to the merge requests that should merge before this work merges. References
+ are in the form of `path/to/project!merge_request_id`.
+1. Select **Create merge request**.
+
+## Edit a merge request to add a dependency
+
+You can edit an existing merge request and mark it as dependent on another.
+
+Prerequisite:
+
+- You must have at least the Developer role or be allowed to edit merge requests in the project.
+
+To do this:
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Merge requests** and identify your merge request.
+1. Select **Edit**.
+1. In **Merge request dependencies**, paste either the reference or the full URL
+ to the merge requests that should merge before this work merges. References
+ are in the form of `path/to/project!merge_request_id`.
+
+## Remove a dependency from a merge request
+
+You can edit a dependent merge request and remove a dependency.
+
+Prerequisite:
+
+- You must have a role in the project that allows you to edit merge requests.
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Merge requests** and identify your merge request.
+1. Select **Edit**.
+1. Scroll to **Merge request dependencies** and select **Remove** next to the reference
+ for each dependency you want to remove.
+
+ NOTE:
+ Dependencies for merge requests you don't have access to are displayed as
+ **1 inaccessible merge request**, and can be removed the same way.
+1. Select **Save changes**.
+
+## Troubleshooting
+
+### API support for managing merge request dependencies
+
+No API support exists for managing dependencies. For more information, read
+[issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551).
+
+### Preserving dependencies on project import or export
+
+Dependencies are not preserved when projects are imported or exported. For more
+information, read [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549).
+
+### Complex merge order dependencies are unsupported
+
+GitLab supports direct dependencies between merge requests, but does not support
+[indirect (nested) dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/11393).
+
+Acceptable dependency patterns include:
+
+- A single merge request can directly depend on a single merge request.
+- A single merge request can directly depend on multiple merge requests.
+- Multiple merge requests can directly depend on a single merge request.
+
+The indirect, nested dependency between `myfriend/library!10` and `mycorp/example!100` shown in this example is not supported:
+
+```mermaid
+graph LR;
+ A[myfriend/library!10]-->|depends on| B[herfriend/another-lib!1]
+ B-->|depends on| C[mycorp/example!100]
+```
diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md
index 09ee828ffd3da..9475c0d60ab87 100644
--- a/doc/user/project/merge_requests/getting_started.md
+++ b/doc/user/project/merge_requests/getting_started.md
@@ -66,7 +66,7 @@ After you have created the merge request, you can also:
- [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread.
- [Perform inline code reviews](reviews/index.md).
-- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged.
+- Add [merge request dependencies](dependencies.md) to restrict it to be merged only when other merge requests have been merged.
- Preview continuous integration [pipelines on the merge request widget](widgets.md).
- Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps).
- [Allow collaboration on merge requests across forks](allow_collaboration.md).
diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md
index 0c4815544011d..6242a77e93144 100644
--- a/doc/user/project/merge_requests/merge_request_dependencies.md
+++ b/doc/user/project/merge_requests/merge_request_dependencies.md
@@ -1,163 +1,11 @@
---
-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: 'dependencies.md'
+remove_date: '2022-11-22'
---
-# Merge request dependencies **(PREMIUM)**
+This document was moved to [another location](dependencies.md).
-A single feature can span several merge requests, spread out across multiple projects,
-and the order in which the work merges can be significant. Use merge request dependencies
-when it's important to merge work in a specific order. Some examples:
-
-- Ensure changes to a required library are merged before changes to a project that
- imports the library.
-- Prevent a documentation-only merge request from merging before the feature work
- is itself merged.
-- Require a merge request updating a permissions matrix to merge, before merging work
- from someone who hasn't yet been granted permissions.
-
-If your project `me/myexample` imports a library from `myfriend/library`,
-you might want to update your project to use a new feature in `myfriend/library`.
-However, if you merge changes to your project before the external library adds the
-new feature, you would break the default branch in your project. A merge request
-dependency prevents your work from merging too soon:
-
-```mermaid
-graph TB
- A['me/myexample' project]
- B['myfriend/library' project]
- C[Merge request #1:<br>Create new version 2.5]
- D[Merge request #2:<br>Add version 2.5<br>to build]
- A-->|contains| D
- B---->|contains| C
- D-.->|depends on| C
- C-.->|blocks| D
-```
-
-You could mark your `me/myexample` merge request as a [draft](drafts.md)
-and explain why in the comments. However, this approach is manual and does not scale, especially
-if your merge request relies on several others in multiple projects. Instead,
-use the draft (or ready) state to track the readiness of an individual
-merge request, and a merge request dependency to enforce merge order.
-
-NOTE:
-Merge request dependencies are a **PREMIUM** feature, but this restriction is
-enforced only for the dependent merge request. A merge request in a **PREMIUM**
-project can depend on a merge request in a **FREE** project, but a merge request
-in a **FREE** project cannot be marked as dependent.
-
-## View dependencies for a merge request
-
-If a merge request is dependent on another, the merge request reports section shows
-information about the dependency:
-
-
-
-To view dependency information on a merge request:
-
-1. On the top bar, select **Menu > Projects** and find your project.
-1. On the left sidebar, select **Merge requests** and identify your merge request.
-1. Scroll to the merge request reports area. Dependent merge requests display information
- about the total number of dependencies set, such as
- **(status-warning)** **Depends on 1 merge request being merged**.
-1. Select **Expand** to view the title, milestone, assignee, and pipeline status
- of each dependency.
-
-Until your merge request's dependencies all merge, your merge request
-cannot be merged. The message
-**Merge blocked: you can only merge after the above items are resolved** displays.
-
-### Closed merge requests
-
-Closed merge requests still prevent their dependents from being merged, because
-a merge request can close regardless of whether or not the planned work actually merged.
-
-If a merge request closes and the dependency is no longer relevant,
-remove it as a dependency to unblock the dependent merge request.
-
-## Create a new dependent merge request
-
-When you create a new merge request, you can prevent it from merging until after
-other specific work merges, even if the merge request is in a different project.
-
-Prerequisites:
-
-- You must have at least the Developer role or be allowed to create merge requests in the project.
-- The dependent merge request must be in a project in a **PREMIUM** or higher tier.
-
-To create a new merge request and mark it as dependent on another:
-
-1. [Create a new merge request](creating_merge_requests.md).
-1. In **Merge request dependencies**, paste either the reference or the full URL
- to the merge requests that should merge before this work merges. References
- are in the form of `path/to/project!merge_request_id`.
-1. Select **Create merge request**.
-
-## Edit a merge request to add a dependency
-
-You can edit an existing merge request and mark it as dependent on another.
-
-Prerequisite:
-
-- You must have at least the Developer role or be allowed to edit merge requests in the project.
-
-To do this:
-
-1. On the top bar, select **Menu > Projects** and find your project.
-1. On the left sidebar, select **Merge requests** and identify your merge request.
-1. Select **Edit**.
-1. In **Merge request dependencies**, paste either the reference or the full URL
- to the merge requests that should merge before this work merges. References
- are in the form of `path/to/project!merge_request_id`.
-
-## Remove a dependency from a merge request
-
-You can edit a dependent merge request and remove a dependency.
-
-Prerequisite:
-
-- You must have a role in the project that allows you to edit merge requests.
-
-1. On the top bar, select **Menu > Projects** and find your project.
-1. On the left sidebar, select **Merge requests** and identify your merge request.
-1. Select **Edit**.
-1. Scroll to **Merge request dependencies** and select **Remove** next to the reference
- for each dependency you want to remove.
-
- NOTE:
- Dependencies for merge requests you don't have access to are displayed as
- **1 inaccessible merge request**, and can be removed the same way.
-1. Select **Save changes**.
-
-## Troubleshooting
-
-### API support for managing merge request dependencies
-
-No API support exists for managing dependencies. For more information, read
-[issue #12551](https://gitlab.com/gitlab-org/gitlab/-/issues/12551).
-
-### Preserving dependencies on project import or export
-
-Dependencies are not preserved when projects are imported or exported. For more
-information, read [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549).
-
-### Complex merge order dependencies are unsupported
-
-GitLab supports direct dependencies between merge requests, but does not support
-[indirect (nested) dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/11393).
-
-Acceptable dependency patterns include:
-
-- A single merge request can directly depend on a single merge request.
-- A single merge request can directly depend on multiple merge requests.
-- Multiple merge requests can directly depend on a single merge request.
-
-The indirect, nested dependency between `myfriend/library!10` and `mycorp/example!100` shown in this example is not supported:
-
-```mermaid
-graph LR;
- A[myfriend/library!10]-->|depends on| B[herfriend/another-lib!1]
- B-->|depends on| C[mycorp/example!100]
-```
+<!-- This redirect file can be deleted after <2022-11-22>. -->
+<!-- Redirects that point to other docs in the same project expire in three months. -->
+<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
--
GitLab