From 7f63cb368856e73bb61f9350f3fe2b22fe97f43e Mon Sep 17 00:00:00 2001
From: Fran Garcia-Linares <14157-fjgarlin@users.noreply.drupalcode.org>
Date: Thu, 18 Jul 2024 10:44:13 +0000
Subject: [PATCH] =?UTF-8?q?Issue=20#3439644=20by=20jonathan1055,=20fjgarli?=
 =?UTF-8?q?n,=20FeyP,=20G=C3=A1bor=20Hojtsy:=20Review=20all=20documentatio?=
 =?UTF-8?q?n=20pages?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/index.md                  |  2 +-
 docs/info/drupal7.md           |  4 ++--
 docs/info/setup.md             |  7 ++++++-
 docs/jobs/composer.md          |  6 ++----
 docs/jobs/cspell.md            |  2 +-
 docs/jobs/phpstan.md           | 19 ++++++++++++++-----
 docs/jobs/phpunit.md           | 10 ++++++++--
 docs/jobs/test-only-changes.md | 10 +++++-----
 docs/jobs/upgrade-status.md    |  4 ++++
 mkdocs.yml                     |  1 +
 10 files changed, 44 insertions(+), 21 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index eb9e8169..0d63d4af 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,7 +5,7 @@ hide:
 
 # GitLab Templates
 
-The GitLab Templates project drives the GitLab CI integration for all Drupal contrib modules.
+The GitLab Templates project drives the GitLab CI integration for all Drupal contrib modules. The project page is located [here](https://www.drupal.org/project/gitlab_templates).
 
 ## Documentation
 
diff --git a/docs/info/drupal7.md b/docs/info/drupal7.md
index 82b8324b..9c56856f 100644
--- a/docs/info/drupal7.md
+++ b/docs/info/drupal7.md
@@ -3,13 +3,13 @@
 To run gitlab pipelines in a Drupal 7 project, create a `.gitlab-ci.yml` file from the standard template as explained [here](./setup.md). Then change one line from this:
 
 ```
-      - '/includes/include.drupalci.main.yml'
+- '/includes/include.drupalci.main.yml'
 ```
 
 to this:
 
 ```
-      - '/includes/include.drupalci.main-d7.yml'
+- '/includes/include.drupalci.main-d7.yml'
 ```
 
 ## Drupal 7 core version
diff --git a/docs/info/setup.md b/docs/info/setup.md
index 3967daf6..79a6d73c 100644
--- a/docs/info/setup.md
+++ b/docs/info/setup.md
@@ -61,4 +61,9 @@ include:
   - remote: https://git.drupalcode.org/${_GITLAB_TEMPLATES_REPO}/-/raw/${_GITLAB_TEMPLATES_REF}/includes/include.drupalci.workflows.yml
 ```
 
-And note that `_GITLAB_TEMPLATES_REPO` and `_GITLAB_TEMPLATES_REF` would need to be defined in your instance too.
+And note that `_GITLAB_TEMPLATES_REPO` and `_GITLAB_TEMPLATES_REF` would need to be defined in your instance too. If you do not want to define these variables you can also hardcode the values to be `project/gitlab_templates` and `default-ref` (or your preferred reference). For example:
+```
+include:
+  - remote: https://git.drupalcode.org/project/gitlab_templates/-/raw/default-ref/includes/include.drupalci.main.yml
+  ...
+```
diff --git a/docs/jobs/composer.md b/docs/jobs/composer.md
index 4e55dca9..21be08fc 100644
--- a/docs/jobs/composer.md
+++ b/docs/jobs/composer.md
@@ -1,12 +1,10 @@
 # Composer
 
-The composer jobs are run automatically every time a related job needs something from `composer`.
-
-You cannot skip them unless you skip testing for a given Drupal variant (current, previous, next).
+The Composer jobs are run automatically if a related job needs something from `composer`. You cannot skip the Composer job unless you skip phpunit testing and also skip every validation/linting job that needs Composer.
 
 ## Updating dependencies when testing against future releases
 
-When testing against future releases, dependencies may not be compatible with the target release, so will need help to enable the test.
+When testing against future versions of Drupal, the minimum stability value is automatically set to ‘dev’, regardless of the value set in `composer.json`. Some dependencies may not be compatible with the target release, so they may need help to be enabled, using Lenient support and/or Composer patches.
 
 ### Lenient support
 
diff --git a/docs/jobs/cspell.md b/docs/jobs/cspell.md
index 25e9f3e9..3aeb3bc6 100644
--- a/docs/jobs/cspell.md
+++ b/docs/jobs/cspell.md
@@ -30,7 +30,7 @@ To disable all spell checking on the next line of a file add a comment `cspell:d
 ### Disable spell checking for a block of lines
 To disable all checking within a block of lines, add a comment `cspell:disable` at the start of the block and `cspell:enable` at the end. This can also be used to ignore the entire file, by adding `cspell:disable` at the top but not having any corresponding `cspell:enable`
 
-For `.md` files you can use the comment style `[//]: # cspell:disable` and `[//]: # cspell:enable`
+For `.md` files you can use the comment style `<!--- cspell:ignore word -->`
 
 For `.json` files you can use the property name `_comment` which is ignored by json validation, so you would have `"_comment": "cspell:disable",` at the start and `"_comment": "cspell:enable",` at the end of the section to ignore.
 
diff --git a/docs/jobs/phpstan.md b/docs/jobs/phpstan.md
index 4a35ac99..d81acd1b 100644
--- a/docs/jobs/phpstan.md
+++ b/docs/jobs/phpstan.md
@@ -1,13 +1,22 @@
 # PHPStan
 
-This job runs [phpstan](https://phpstan.org/) checks on your module.
+The [PHPStan](https://phpstan.org/) job runs static code quality checks.
 
-If there is a baseline file in the module it will use it, but if there isn't, it will just run default values.
+If the project contains a `phpstan.neon` configuration file it will be used. If not, a [default configuration](https://git.drupalcode.org/project/gitlab_templates/-/blob/main/assets/phpstan.neon) is used.
 
-It will offer a baseline file for module maintainers to add it to their projects to make adoption easier.
+The pipeline variable `_PHPSTAN_LEVEL` can be set to a value from 0-9 to specify how relaxed or severe the code quality checks should be. This can be used to temporarily override the value in your `phpstan.neon` file. If no value is given, either in the variable or the fle, then the default of 0 is used. See https://phpstan.org/user-guide/rule-levels for more information.
 
-If you do not want it to run in your contrib module, you just need to set `SKIP_PHPSTAN` to 1.
+Projects can specify [baseline](https://phpstan.org/user-guide/baseline) file(s) of messages to ignore, using the `includes:` keyword in the `phpstan.neon` file:
+```
+includes:
+  - your-baseline-file.neon
+  - second-baseline-file.neon
+```
 
-This job allows multiple variants to check current and future versions of Drupal, as well as the maximum PHP version.
+Any warnings that are found are written to a new baseline file which is available as a job artifact for download. These can be added into the existing baseline file until the code is fixed. Unmatched messages in the baseline file are also reported in the log.
+
+In addition to testing at the current core version, the `PHPStan` job has optional variants for the next major and minor core versions and the maximum PHP version.
 
 Consider the PHP version when interpreting the results of the PHPStan job, as the analysis may give different results between major versions of PHP.
+
+If you do not want this job to be run, set the variable `SKIP_PHPSTAN: 1`
diff --git a/docs/jobs/phpunit.md b/docs/jobs/phpunit.md
index 80097fe5..7266860b 100644
--- a/docs/jobs/phpunit.md
+++ b/docs/jobs/phpunit.md
@@ -99,6 +99,12 @@ phpunit (next major):
 ```
 
 
+The variants inherit customizations made in the `phpunit` job. If you don't want these to propagate to the variants, you could extend the variants from the `.phpunit-base` job, like this:
+```
+phpunit (next major):
+  extends: !reference [.phpunit-base]
+```
+
 ## Deprecations
 
 By default, we are setting `SYMFONY_DEPRECATIONS_HELPER` to `disabled`. This will not report warnings or deprecations by default.
@@ -110,7 +116,7 @@ phpunit:
     SYMFONY_DEPRECATIONS_HELPER: "ignoreFile=$CI_PROJECT_DIR/$_WEB_ROOT/core/.deprecation-ignore.txt"
 ```
 
-If you are testing with Drupal 10 (which uses PHPUnit 9), your project needs to have a PHPUnit configuration file to be able to get deprecation warnings. The most minimal required configuration is shown below. This file will need to load the `DrupalListener` class, as shown below. This is not needed for Drupal 11 (which uses PHPUnit 10):
+If you are testing with Drupal 10 (which uses PHPUnit 9), and are running phpunit direct via `_PHPUNIT_CONCURRENT: 0`, your project needs to have a PHPUnit configuration file (`phpunit.xml`) to be able to get deprecation warnings. This file needs to load the `DrupalListener` class and the most minimal required configuration is shown below. This is not needed for Drupal 11 (which uses PHPUnit 10):
 ```
  <?xml version="1.0" encoding="UTF-8"?>
  <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
@@ -121,7 +127,7 @@ If you are testing with Drupal 10 (which uses PHPUnit 9), your project needs to
  </phpunit>
 ```
 
-If you want to have your own file to include other deprecations, like third party ones, you can create your own file and call it like this:
+If you want to report other deprecations, like third party ones, you can create your own deprecations file and call it like this:
 ```
 phpunit:
   variables:
diff --git a/docs/jobs/test-only-changes.md b/docs/jobs/test-only-changes.md
index 57958e51..37da21e2 100644
--- a/docs/jobs/test-only-changes.md
+++ b/docs/jobs/test-only-changes.md
@@ -1,15 +1,15 @@
 # Test-only changes
 
-The purpose of this job is to run only the tests that have been modified in a Merge Request. All the non-test files are reverted back to their unchanged state.
+The `test-only changes` job does not run the full set of phpunit tests, but instead it just runs the tests that have been modified in a Merge Request. Additionally all of the non-test files are reverted back to their unchanged state.
 
-This is a way to demonstrate that the changes in the tests provide test coverage for the feature/bug/problem which is being worked on. It is equivalent to the "test-only will fail" patches that have been used on DrupalCI for contrib projects and for core over the past years. Drupal Core already has a 'test-only changes' GitLab pipeline job, but this feature is new for contrib projects.
+The purpose of this job is to demonstrate that the changes in the tests provide test coverage for the feature/bug/problem which is being worked on. It is equivalent to the "test-only will fail" patches that have been used on DrupalCI for contrib projects and for core over the past years. Drupal Core already has a 'test-only changes' GitLab pipeline job, but this feature is new for contrib projects.
 
 This job is only created in Merge Request pipelines, it will not appear in branch or scheduled pipelines. It will only be created if the merge request actually contains changes to phpunit test files.
 
-It is `manual`, which means it will not start automatically but will require you to click the `[>]` 'play' button.
+It is `manual`, which means it is optional and will not start automatically, but requires you to click the `[>]` 'play' button.
 
 The log has extra information showing which files have been changed in the merge request and which files have been reverted before running the tests. The job is intended to fail with an amber warning, as this demonstrates that the modified tests do provide test coverage for the problem being fixed.
 
-If this job ends with a green pass it means that the bug or feature does not have test coverage, because the tests pass even with unmodified source files.
+If this job ends with a green pass it means that the bug or feature does not have test coverage, because the tests pass even with the unmodified source files.
 
-If you chose not to trigger the job at all, your pipeline result will not be affected.
+It can also be used to demonstrate new test coverage for existing source code which is not being changed. To do this, make a temporary change to the source (to simulate a bug) which will cause the new test to fail in the regular `phpunit` job. However the `test-only changes` job should pass green. This is the reverse outcome compared the usual scenario described above, but it does indicate that the new test provides coverage as intended. 
diff --git a/docs/jobs/upgrade-status.md b/docs/jobs/upgrade-status.md
index fd0ded29..6880ac85 100644
--- a/docs/jobs/upgrade-status.md
+++ b/docs/jobs/upgrade-status.md
@@ -27,3 +27,7 @@ You can pass additional arguments to the `drush upgrade_status:analyze` command
 variables:
   _UPGRADE_STATUS_ANALYZE_EXTRA: '--extra --options'
 ```
+
+## How does this job compare with the "next major" job?
+
+The "Upgrade status" job is an individual job as opposed to a full variant (composer + phpstan + phpunit + nightwatch). It can also help you with the fixes, as opposed to just showing the errors.
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index e8f791f9..cdbd9719 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -51,6 +51,7 @@ nav:
     - test-only changes: 'jobs/test-only-changes.md'
     - nightwatch: 'jobs/nightwatch.md'
     - pages: 'jobs/pages.md'
+    - upgrade status: 'jobs/upgrade-status.md'
   - Help us:
     - Help us: 'help/help.md'
     - With the code: 'help/contributing.md'
-- 
GitLab