>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3423238. --> Reported by: [mparker17](https://www.drupal.org/user/536298) Related to !177 !144 >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <blockquote><p> 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. </p></blockquote> <p>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 <em>could</em> document this type of feature).</p> <p>I also discovered that Drupal.org's GitLab CI pipeline configuration checks a <code>SKIP_*</code> variable for each job we've added, to allow skipping that job, but that wasn't documented anywhere either, and the <a href="https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-drupal/gitlab-ci">the GitLab CI on Drupal.org overview page</a> seems like a poor place to document that since we only want people to do that as a last resort.</p> <p>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.).</p> <p>(Note: this issue is distinct from <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/gitlab_templates/-/issues/3424756" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/gitlab_templates/-/issues/3424756</a></span> &mdash; 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)</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <ol> <li><del>Add a section to the Drupal Wiki (or similar)</del> <strong>Create a documentation site using GitLab Pages</strong> to document how to customize the linters/testers run by Drupal.org's GitLab CI and everything else related to what these templates offer.</li> <li>Add a "general best practices for module maintainers" page to this section.</li> <li>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.</li> <li>Add a "how to skip a job if all else fails" page to this section to document the <code>SKIP_*</code> variables.</li> </ol> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <p>To be agreed-upon, probably something like the proposed resolution.</p> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None.</p> > Related issue: [Issue #3424756](https://www.drupal.org/node/3424756) > Related issue: [Issue #3423402](https://www.drupal.org/node/3423402)