There is frequent confusion about how merge request pipelines work

Problem

From time to time we get issues opened like #369383 (closed) that have a series of customers writing about "bugs" they're experiencing that are usually not bugs, but misunderstandings of how to configure their pipelines for merge requests. When the expect to see the pipelines, what variables they expect to have populated etc. Responding to these complaints is time consuming and difficult since the functionality is often not obvious, but rarely requires any development work.

For example, today I learned that a child pipeline created by a merge request pipeline will have merge-request related variables, but it's source will be parent_pipeline, not anything related to merge requests. So the MR pipeline config that works for a parent pipeline config:

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

doesn't work the same way in a child pipeline config. That's just something you have to know.

Proposal

I would like to create a big chart of actions (Push to a branch, open a merge request, etc.), the kinds of pipelines those actions can produce, and what those produces pipelines will be like given certain configuration.

Sometimes the behavior of our CI platform isn't super intuitive, but there are many paths so it's difficult to think about all the possibilities at once. We have documentation around all the individual parts and possibilities, but I think a chart or diagram would help people answer the question "What sort of pipeline have I created?", and in turn be able to find their way to more specific documentation.