#3425446: Documentation page.

docs/index.md

@@ -11,7 +11,7 @@ The GitLab Templates project drives the GitLab CI integration for all Drupal con
 
 The [GitLab CI](https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-drupal/gitlab-ci) page offers an introduction to most of the topics.
 
-This documentation site offers further insight into individual jobs, best practices, etc. 
+This documentation site offers further insight into individual jobs, best practices, etc.
 
 ## Basic information
 
@@ -36,6 +36,7 @@ Jump straight to the individual job's documentation page:
 - [cspell](./jobs/cspell.md)
 - [phpstan](./jobs/phpstan.md)
 - [stylelint](./jobs/stylelint.md)
+- [eslint](./jobs/eslint.md)
 - [phpcs](./jobs/phpcs.md)
 - [composer-lint](./jobs/composer-lint.md)
 - [phpunit](./jobs/phpunit.md)

docs/info/validation-jobs.md

+# Validation jobs
+
+There are several code validation jobs, trying to mirror what core does.
+There is documentation for each of those jobs in:
+
+- [cspell](../jobs/cspell.md)
+- [phpstan](../jobs/phpstan.md)
+- [stylelint](../jobs/stylelint.md)
+- [eslint](./jobs/eslint.md)
+- [phpcs](../jobs/phpcs.md)
+- [composer-lint](../jobs/composer-lint.md)
+
+## Allow failure in pipelines
+
+By default, all validation jobs are allowed to fail. This means that even if the job fails, the overall result of the pipeline will not be affected by it.
+
+If the overall result of the pipeline is successful, and any of the validation jobs fail, then a warning icon will show.
+
+There are several ways to alter this behavior, listed below.
+
+### All validation jobs
+There is a special variable, named `_ALL_VALIDATE_ALLOW_FAILURE`, to control all the validation jobs `allow_failure`-behavior at once. Set to 1 to allow the all the validation/linting jobs to fail, set to 0 for not allowing any failure. Individual job variables can override this global settings.
+```
+variables:
+  _ALL_VALIDATE_ALLOW_FAILURE: 0
+```
+
+### Per job
+There are individual variables to allow each job to fail (default value) or not. You just need to set these values to `0` in the `variables:` section in your `.gitlab-ci.yml` file, as shown below:
+```
+variables:
+  _COMPOSER_LINT_ALLOW_FAILURE: 0
+  _PHPCS_ALLOW_FAILURE: 0
+  _STYLELINT_ALLOW_FAILURE: 0
+  _CSPELL_ALLOW_FAILURE: 0
+  _ESLINT_ALLOW_FAILURE: 0
+  _PHPSTAN_ALLOW_FAILURE: 0
+```
+
+### Override the job value
+If you don't want to use any of the above variables, you can simply override the job value definition in your `.gitlab-ci.yml` file for the linting jobs where you want to change this behavior.
+
+```
+cspell:
+  allow_failure: false
+```

mkdocs.yml

@@ -34,6 +34,7 @@ nav:
       - Set up: 'info/setup.md'
       - Common tasks: 'info/common.md'
       - Customizations: 'info/customizations.md'
+      - Validation jobs: 'info/validation-jobs.md'
       - Variants (Drupal versions): 'info/variants.md'
       - Test Merge Requests: 'info/testing-mrs.md'
       - Test locally: 'info/test-locally.md'