Document how to use and customize GitLabCI with mkdocs and a Pages job
Problem/Motivation
As a module maintainer using Drupal.org's GitLab CI to make my module easier to maintain, I want to be able to find documentation on how to customize the behavior of the linters / testers run on my module, so that I can make the best use of my contribution time.
While trying to add GitLab CI configuration to one of the projects I maintain, a newly-added lint started failing, notifying me about things I didn't want to fix until I had the rest of the pipeline running, i.e.: so my regression tests could tell me if I broke something. This particular linter had been added to the default GitLab CI pipeline 2 days earlier, but there was no documentation for it. After a bit of digging, it seemed like I could add a configuration file to ignore those things (a "baseline" to borrow a term from another linter), but this wasn't documented anywhere (and there didn't seem to be a place in the wiki where people who contribute a new lint could document this type of feature).
I also discovered that Drupal.org's GitLab CI pipeline configuration checks a SKIP_* variable for each job we've added, to allow skipping that job, but that wasn't documented anywhere either, and the the GitLab CI on Drupal.org overview page seems like a poor place to document that since we only want people to do that as a last resort.
There also doesn't appear to be a place to document general best practices for module maintainers (e.g.: skip lints with a "baseline" file and file a follow-up issue, instead of skipping the job altogether, so that code being added by contributors gets linted and you don't have more work later, etc.).
(Note: this issue is distinct from #3424756 (closed) — 3424756 is about how to fix lints that a maintainer does want to run; while this issue is about how to customize GitLab CI and the jobs it runs, including how to stop linter jobs from running)
Proposed resolution
-
Add a section to the Drupal Wiki (or similar)Create a documentation site using GitLab Pages to document how to customize the linters/testers run by Drupal.org's GitLab CI and everything else related to what these templates offer. - Add a "general best practices for module maintainers" page to this section.
- Add pages for each of the validation and test jobs that run (at time-of-writing, those are: composer-lint, phpcs, phpstan, stylelint, eslint, cspell, nightwatch, and phpunit). If that job's behavior cannot be customized, then state that. If its behavior can be customized, document how to do that.
- Add a "how to skip a job if all else fails" page to this section to document the
SKIP_*variables.
Remaining tasks
To be agreed-upon, probably something like the proposed resolution.
User interface changes
None.
API changes
None.
Data model changes
None.
Related issue: Issue #3424756
Related issue: Issue #3423402