From 66acda2c67823269eac7c07bf782684bf6bfb02f Mon Sep 17 00:00:00 2001
From: Fran Garcia-Linares <fjgarlin@gmail.com>
Date: Fri, 17 Jan 2025 12:08:03 +0100
Subject: [PATCH] #3425446: Documentation page.
---
docs/index.md | 3 ++-
docs/info/validation-jobs.md | 46 ++++++++++++++++++++++++++++++++++++
mkdocs.yml | 1 +
3 files changed, 49 insertions(+), 1 deletion(-)
create mode 100644 docs/info/validation-jobs.md
diff --git a/docs/index.md b/docs/index.md
index 414939b7..76e08075 100644
--- a/docs/index.md
+++ b/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)
diff --git a/docs/info/validation-jobs.md b/docs/info/validation-jobs.md
new file mode 100644
index 00000000..dc5df3dd
--- /dev/null
+++ b/docs/info/validation-jobs.md
@@ -0,0 +1,46 @@
+# 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
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index eb003922..cc2436b3 100644
--- a/mkdocs.yml
+++ b/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'
--
GitLab