From e718a036de8ca53bb8eb8861d902ec51ea11a4d7 Mon Sep 17 00:00:00 2001
From: Jonathan Smith <20701-jonathan1055@users.noreply.drupalcode.org>
Date: Tue, 10 Dec 2024 11:34:39 +0000
Subject: [PATCH] Issue #3473000 by jonathan1055, fjgarlin: Documentation pages

---
 CHANGELOG.md                   |  2 +-
 docs/info/customizations.md    |  2 +-
 docs/info/templates-version.md |  5 ++++-
 docs/info/variants.md          |  5 +++--
 docs/jobs/eslint.md            | 20 +++++++++++---------
 docs/jobs/phpunit.md           | 19 +++++--------------
 mkdocs.yml                     |  2 +-
 7 files changed, 26 insertions(+), 29 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6212efb9..e28aab69 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,7 +21,7 @@
 
 ## 1.6.7 - 2024-11-13
 
-#3486943 - Repo top-level logo does not show in MkDocs pages.
+#3486943 - Repo top-level logo does not show in MkDocs pages.\
 #3486466 - Adjust Core phpunit.xml to make it work for Contrib.\
 #3439021 - Improve internal eslint and prettier checks.\
 #3486983 - Update core stable versions to 10.3.8 and 11.0.7.
diff --git a/docs/info/customizations.md b/docs/info/customizations.md
index e13fca73..2475dd0e 100644
--- a/docs/info/customizations.md
+++ b/docs/info/customizations.md
@@ -15,7 +15,7 @@ variables:
   SKIP_PHPSTAN: 1
 ```
 
-Most variables are global in scope, as in the example above, where the the `variables:` keyword is at the top level. But some variables, such as `DRUPAL_CORE` and `PHP_VERSION` need to be scoped to a particular job, because the value has to change between the different [job variants](./info/variants.md). In this case, use the appropriate composer job name, for example:
+Most variables are global in scope, as in the example above, where the the `variables:` keyword is at the top level. But some variables, such as `DRUPAL_CORE` and `PHP_VERSION` need to be scoped to a particular job, because the value has to change between the different [job variants](./variants.md). In this case, use the appropriate composer job name, for example:
 
 ```
 composer:
diff --git a/docs/info/templates-version.md b/docs/info/templates-version.md
index 1c054c4d..176da04d 100644
--- a/docs/info/templates-version.md
+++ b/docs/info/templates-version.md
@@ -34,4 +34,7 @@ There may be times when you want to verify which commits are contained in a part
 
 - What commits are in the `default` release? [Commits](https://git.drupalcode.org/project/gitlab_templates/-/commits/default-ref?ref_type=tags)
 
-- What commits are in `main` but not yet in a tagged release? [Commits](https://git.drupalcode.org/project/gitlab_templates/-/compare/default-ref...main?from_project_id=96292)
+- What commits are in `main` but not yet in the `default` release? [Commits](https://git.drupalcode.org/project/gitlab_templates/-/compare/default-ref...main?from_project_id=96292)
+
+- Here are the commits that are [not yet in the `1.x-latest` release](https://git.drupalcode.org/project/gitlab_templates/-/compare/1.x-latest...main)
+
diff --git a/docs/info/variants.md b/docs/info/variants.md
index 44a96cd3..957a006e 100644
--- a/docs/info/variants.md
+++ b/docs/info/variants.md
@@ -1,8 +1,9 @@
-# Variants
+# Variants (Drupal versions)
 
 ## Available variants
 
-The templates support testing not only the current version (on by default), but also the previous minor and major, and the next minor and major.
+The templates support testing not only the current version of Drupal (on by default), but also the previous minor and major versions, and the next minor and major versions. We call these versions "variants" throughout the documentation.
+
 All of these variants can be opted-in via the `OPT_IN_` variables.
 
 The available opt-in variables are:
diff --git a/docs/jobs/eslint.md b/docs/jobs/eslint.md
index 40a485ae..94785702 100644
--- a/docs/jobs/eslint.md
+++ b/docs/jobs/eslint.md
@@ -1,30 +1,32 @@
 # ESLint
 
-The `eslint` job checks coding standards in `.js` and `.yml` files.
+The `eslint` job checks formatting standards in `.js` and `.yml` files.
 
-[ESLint](https://eslint.org/) can be configured using a `.eslintrc.json` file placed in your projects root directory. This is not mandatory, and if no such file exists then a default one matching Core's standards `core/.eslintrc.passing.json` is used. If you do create a `.eslintrc.json` file then it only needs to contain the specific rules that you want to override, because all other rules will be inherited from Core due to ESLint's cascading configuration.
+[ESLint](https://eslint.org/) can be configured using an `.eslintrc.json` file that is located in your project's root directory. This file is optional and if it does not exist then a default configuration file with the same settings as `core/.eslintrc.passing.json` will be used. If you do create an `.eslintrc.json` file, it only needs to contain the specific rules that you want to override; all other rules will be inherited from the Core configuration because ESLint configuration cascades.
 
-You can pass additional options to the `eslint` call via the `_ESLINT_EXTRA` variable. This variable has a default value of `--quiet` to match what Drupal core does.
+You can pass additional options to `eslint` via the `_ESLINT_EXTRA` variable. This variable has a default value of `--quiet` to match what Drupal core does.
 
-If there are `.js` or `.yml` files that you do not want to fix, or cannot fix for whatever reason, these can be ignored by adding the names to a `.eslintignore` file stored in your project top-level folder. Files and paths listed here will be completely ignored for both ESLint and Prettier checking. An example where this would be needed is if you have minified javascript files.
+If there are `.js` or `.yml` files that you do not want to fix, or if you cannot fix them for whatever reason, you can specify that the files should be ignored by adding the names to an `.eslintignore` file that is located in your project's root directory. Files and paths listed in `.eslintignore` will be ignored by both the ESLint and Prettier checks. For example, if your project contains minified javascript files these need to be ignored, so your `.eslintignore` should contain:
 ```
 # Ignore all minified javascript files
 **/*.min.js
 ```
-### Extra Dependencies
-If your project requires `ckeditor`-specific linting, and you have the dependencies in a `package.json` file then you can install them using:
+### Extra Dependencies for CKEditor
+If your project requires linting of `js` for `ckeditor`, and if the relevant dependencies are listed in a `package.json` file, then you can install those dependencies by adding the following to your `.gitlab-ci.yml`:
 ```
 composer:
   after_script:
     - npm ci
 ```
-Note that if you also have a `package-lock.json`, use `npm ci` to install dependencies instead of `npm install`. This is because `npm install` may install dependencies that are more up-to-date than what is specified in `package-lock.json`, whereas `npm ci` will install exactly what is specified in the `package-lock.json`.
+You could use `npm install`, but if you have a `package-lock.json`, use `npm ci` instead because `npm install` may install dependencies that are more up-to-date than what is specified in `package-lock.json`, whereas `npm ci` will install exactly what is specified in `package-lock.json`.
 
 ## Prettier
 
-"Prettier" processing is the part of ESLint that is concerned with formatting and file layout, for both `.js` and `.yml` files. Formatting rules follow the definitions used by Drupal Core as defined in `core/.prettierrc.json`. This is the default, but projects can have their own definitions in a `.prettierrc.json` file which will be used instead of the core rules. Unlike ESLint, the Prettier rules do not use cascading configuration, so if you do have a `.prettierrc.json` file it must contain all the rules that you want your project to follow.
+[Prettier](https://prettier.io/) makes the formatting of both `.js` and `.yml` files "prettier", and is run as part of the `eslint` job.
 
-If there are files that you do not want to fix, or cannot fix, for Prettier formatting, these can be ignored by adding the file paths to a `.prettierignore` file. An example where this is needed is the Config and Views files exported from UI, as these do not follow the Prettier formatting rules. So rather than manually edit the exported files, they can be ignored for Prettier formatting (but still be checked for ESLint standards).
+Prettier's formatting rules follow the standards specified by Drupal Core as defined in `core/.prettierrc.json`. If you want to specify rules that differ from core's, you can do so in a `.prettierrc.json` file. But unlike ESLint, Prettier rules do not cascade, so if you include a `.prettierrc.json` file, you must specify all of the Core rules that you want your project to follow because they will not be inherited.
+
+You can ignore files that you do not want to fix, or cannot fix, for Prettier formatting, by adding the file paths to a `.prettierignore` file. An example where this is needed is the Config and Views files exported from the UI, as these do not follow Prettier's formatting rules. So rather than manually editing the exported files, you can ignore them for Prettier processing (but still check them with ESLint).
 ```
 config/*/views.*.yml
 tests/modules/*/config/install/*.yml
diff --git a/docs/jobs/phpunit.md b/docs/jobs/phpunit.md
index 3de94702..3d241a9d 100644
--- a/docs/jobs/phpunit.md
+++ b/docs/jobs/phpunit.md
@@ -85,7 +85,7 @@ phpunit (next major):
 
 Drupal 10 uses PHPUnit 9, whereas Drupal 11 uses PHPUnit 10. Because of this, not all `phpunit` options are valid in both versions. If you use `_PHPUNIT_CONCURRENT: 1`, then `run-tests.sh` takes care of these cases for you. However, if you use `_PHPUNIT_CONCURRENT: 0`, you might need to adapt the options per variant as shown in the previous section.
 
-If you do not provide a PHPUnit configuration file in your module, you can opt for using Drupal core's PHPUnit configuration file by setting `_PHPUNIT_EXTRA: '-c $CI_PROJECT_DIR/$_WEB_ROOT/core'` in your variables section.
+If you do not provide a PHPUnit configuration file in your module, the default file from `core/phpunit.xml` will be used.
 
 If you do provide a PHPUnit configuration file in your module, you might need to provide a different one depending on the PHPUnit version. You can achieve it like this (where `phpunit9.xml` and `phpunit10.xml` are files in the root of your repository):
 
@@ -120,25 +120,16 @@ Tests on Drupal 11 and above will use Selenium and the latest Chrome W3C-complia
 
 ## Deprecations
 
-By default, we are setting `SYMFONY_DEPRECATIONS_HELPER` to `disabled`. This will not report warnings or deprecations by default.
+The variable `SYMFONY_DEPRECATIONS_HELPER` is set to `disabled` by default, so that warnings and deprecations are not reported.
 
-If you want to mirror what core does, you can do it like this:
+You can mirror what core does by using the Core `.deprecation-ignore.txt` file. This will only ignore the deprecations that Core ignores:
 ```
-phpunit:
+phpunit (next minor):
   variables:
     SYMFONY_DEPRECATIONS_HELPER: "ignoreFile=$CI_PROJECT_DIR/$_WEB_ROOT/core/.deprecation-ignore.txt"
 ```
 
-If you are testing with Drupal 10 (which uses PHPUnit 9), and are running PHPUnit directly 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">
-   <listeners>
-     <listener class="\Drupal\Tests\Listeners\DrupalListener">
-     </listener>
-   </listeners>
- </phpunit>
-```
+If your project has its own `phpunit.xml(.dist)` file and you are testing with Drupal 10 (which uses PHPUnit 9), running PHPUnit directly via `_PHPUNIT_CONCURRENT: 0`, your file will need to contain the `<listener class="\Drupal\Tests\Listeners\DrupalListener">` class in order to get deprecation warnings. This is not needed for Drupal 11 (which uses PHPUnit 10).
 
 If you want to report other deprecations, like third party ones, you can create your own deprecations file and call it like this:
 ```
diff --git a/mkdocs.yml b/mkdocs.yml
index 0ad1f88e..eb003922 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -34,7 +34,7 @@ nav:
       - Set up: 'info/setup.md'
       - Common tasks: 'info/common.md'
       - Customizations: 'info/customizations.md'
-      - Variants: 'info/variants.md'
+      - Variants (Drupal versions): 'info/variants.md'
       - Test Merge Requests: 'info/testing-mrs.md'
       - Test locally: 'info/test-locally.md'
       - Templates version: 'info/templates-version.md'
-- 
GitLab