Merge branch 'docs-pipeline-needs-view' into 'master'

Add docs for new "needs dependency" pipeline view

See merge request gitlab-org/gitlab!60262

doc/ci/directed_acyclic_graph/index.md

@@ -94,3 +94,5 @@ To see the needs visualization, click on the **Needs** tab when viewing a pipeli
 Clicking a node highlights all the job paths it depends on.
 
 ![Needs visualization with path highlight](img/dag_graph_example_clicked_v13_1.png)
+
+You can also see `needs` relationships in [full pipeline graphs](../pipelines/index.md#view-full-pipeline-graph).

doc/ci/jobs/index.md

@@ -65,7 +65,7 @@ you can also see the reason it failed on the Job detail page.
 
 The order of jobs in a pipeline depends on the type of pipeline graph.
 
-- For [regular pipeline graphs](../pipelines/index.md#regular-pipeline-graphs), jobs are sorted by name.
+- For [full pipeline graphs](../pipelines/index.md#view-full-pipeline-graph), jobs are sorted by name.
 - For [pipeline mini graphs](../pipelines/index.md#pipeline-mini-graphs), jobs are sorted by severity and then by name.
 
 The order of severity is:

doc/ci/pipelines/index.md

@@ -325,23 +325,81 @@ Pipelines can be complex structures with many sequential and parallel jobs.
 To make it easier to understand the flow of a pipeline, GitLab has pipeline graphs for viewing pipelines
 and their statuses.
 
-Pipeline graphs can be displayed in two different ways, depending on the page you
+Pipeline graphs can be displayed as a large graph or a miniature representation, depending on the page you
 access the graph from.
 
 GitLab capitalizes the stages' names in the pipeline graphs.
 
-### Regular pipeline graphs
+### View full pipeline graph
 
-> - [Visualization improved](https://gitlab.com/gitlab-org/gitlab/-/issues/276949) in GitLab 13.11.
+> - [Visualization improvements introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276949) in GitLab 13.11.
 
-Regular pipeline graphs show the names of the jobs in each stage. Regular pipeline graphs can
-be found when you are on a [single pipeline page](#view-pipelines). For example:
+The [pipeline details page](#view-pipelines) displays the full pipeline graph of
+all the jobs in the pipeline.
 
-![Pipelines example](img/pipelines_v13_11.png)
+You can group the jobs by:
+
+- Stage, which arranges jobs in the same stage together in the same column.
+
+  ![jobs grouped by stage](img/pipelines_graph_stage_view_v13_12.png)
+
+- [Job dependencies](#view-job-dependencies-in-the-pipeline-graph), which arranges
+  jobs based on their [`needs`](../yaml/README.md#needs) dependencies.
 
 [Multi-project pipeline graphs](../multi_project_pipelines.md#multi-project-pipeline-visualization) help
 you visualize the entire pipeline, including all cross-project inter-dependencies. **(PREMIUM)**
 
+### View job dependencies in the pipeline graph
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298973) in GitLab 13.12.
+> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
+> - Disabled on GitLab.com.
+> - Not recommended for production use.
+> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-job-dependency-view). **(FREE SELF)**
+
+This in-development feature might not be available for your use. There can be
+[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development).
+Refer to this feature's version history for more details.
+
+You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/README.md#needs)
+dependencies.
+
+Jobs in the leftmost column run first, and jobs that depend on them are grouped in the next columns.
+
+For example, `build-job2` depends only on jobs in the first column, so it displays
+in the second column from the left. `deploy-job2` depends on jobs in both the first
+and second column and displays in the third column:
+
+![jobs grouped by needs dependency](img/pipelines_graph_dependency_view_v13_12.png)
+
+To add lines that show the `needs` relationships between jobs, select the **Show dependencies** toggle.
+These lines are similar to the [needs visualization](../directed_acyclic_graph/index.md#needs-visualization):
+
+![jobs grouped by needs dependency with lines displayed](img/pipelines_graph_dependency_view_links_v13_12.png)
+
+To see the full `needs` dependency tree for a job, hover over it:
+
+![single job dependency tree highlighted](img/pipelines_graph_dependency_view_hover_v13_12.png)
+
+#### Enable or disable job dependency view **(FREE SELF)**
+
+The job dependency view is under development and not ready for production use. It is
+deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:pipeline_graph_layers_view)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:pipeline_graph_layers_view)
+```
+
 ### Pipeline mini graphs
 
 Pipeline mini graphs take less space and can tell you at a
@@ -356,6 +414,8 @@ Pipeline mini graphs allow you to see all related jobs for a single commit and t
 of each stage of your pipeline. This allows you to quickly see what failed and
 fix it.
 
+Pipeline mini graphs only display jobs by stage.
+
 Stages in pipeline mini graphs are collapsible. Hover your mouse over them and click to expand their jobs.
 
 | Mini graph                                                   | Mini graph expanded                                            |