Docs feedback: Pipelines for Merge Requests Page Favors Rules, but Gives all examples as only/except
Link the doc and describe what is wrong with it.
First Time Learner Challenges
The important feature Pipelines for Merge Requests is IMO hard to configure as a first time (Out of Box) learner / discoverer due to documentation.
-
This documentation: https://docs.gitlab.com/ee/ci/pipelines/merge_request_pipelines.html mentions that
rules:
are preferred overonly:/except:
- but then all on-page examples areonly:/except:
. -
The information that you are directed to is "workflow rules" - which is:
- not the same as the on-page job rules.
- can have unintended consequences when done incorrectly.
- drops the user into the advanced conversation topics of 1) switching between two includes for branch and merge request pipelines and 2) using includes to manage workflow rules
- does not seem to cover what to do if you don't want workflow rules
- does not seem to cover what to do if you don't want a dependency on gitlab ci templates.
- is not easily implemented when building a reusable extension using
includes:
(because job specific rules have a known scope within the include) (for advanced ci builders)
-
The net result of this documentation algebra would seem likely (for a new learner / discoverer) to be TL;DR; on using any kind of
rules:
and then come back to the original page and implementonly:/except:
- the opposite of the desired behavior.
Suggested Fix
I would like to suggest that the configuration for branches on https://docs.gitlab.com/ee/ci/pipelines/merge_request_pipelines.html be updated to use job level rules.
This would have the benefits of:
- steering folks clear of directly using
only:/except:
(maybe a mention only only on this page - or purposely leave it out?) - provide a clear, simple learning path using the simplest use case - with the option to upgrade to workflow rules and using includes to manage workflow rules later.
- provide an implementation that is more compatible with creating your own Merge Request pipeline extensions that implement their inclusion / exclusion logic at the job level. (for advanced ci builders)
- additionally, I think there would be more uptake of workflow rules and the includes if more context were given on the page where that link lands.
Add Notice About Bug
The work I am doing appears to be suffering from this bug: #297372 - which seems to affect the entire premise of this documentation information - perhaps it should be cited until it is fixed.