GH Actions: add markdown check workflow

.gitattributes

@@ -9,7 +9,10 @@
 /.gitignore export-ignore
 /.cache/ export-ignore
 /.github/ export-ignore
+/.markdownlint-cli2.yaml export-ignore
 /.phpcs.xml.dist export-ignore
+/.remarkignore export-ignore
+/.remarkrc export-ignore
 /phpunit.xml.dist export-ignore
 /tests/ export-ignore
 

.github/RELEASE-CHECKLIST.md

@@ -3,12 +3,12 @@ Template to use for release PRs from `develop` to `main`
 
 Title: Release version x.x.x
 
-### Functional:
+## Functional
 - [ ] Confirm that the most recent PHPUnit changelogs have been checked and that the library is still feature complete for those versions supported within the PHPUnit version constraints.
 - [ ] Update the `VERSION` constant in the `phpunitpolyfills-autoload.php` file.
 - [ ] Composer: check if any dependencies/version constraints need updating.
 
-### Release:
+## Release
 - [ ] Add changelog for the release - PR #xxx
     Verify that a release link at the bottom of the `CHANGELOG.md` file has been added.
 - [ ] Merge this PR.
@@ -20,7 +20,7 @@ Title: Release version x.x.x
 - [ ] Open a new milestone for the next release.
 - [ ] If any open PRs/issues which were milestoned for the release did not make it into the release, update their milestone.
 
-### Announce:
+## Announce
 - [ ] Tweet about the release.
 
 

.github/workflows/markdown.yml

@@ -0,0 +1,112 @@
+name: MarkDown
+
+on:
+  # Run on all pushes and on all pull requests.
+  push:
+  pull_request:
+  # Also run this workflow every Monday at 6:00.
+  schedule:
+    - cron: '0 6 * * 1'
+  # Allow manually triggering the workflow.
+  workflow_dispatch:
+
+# Cancels all previous workflow runs for the same branch that have not yet completed.
+concurrency:
+  # The concurrency group contains the workflow name and the branch name.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  markdownlint:
+    name: 'Lint Markdown'
+    runs-on: ubuntu-latest
+
+    # Don't run the cronjob in this workflow on forks.
+    if: github.event_name != 'schedule' || (github.event_name == 'schedule' && github.repository_owner == 'Yoast')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      # This action also handles the caching of the dependencies.
+      # https://github.com/actions/setup-node
+      - name: Set up node and enable caching of dependencies
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      # @link https://github.com/DavidAnson/markdownlint-cli2
+      # @link https://github.com/DavidAnson/markdownlint
+      - name: Install Markdownlint CLI2
+        run: npm install -g markdownlint-cli2
+
+      # @link https://github.com/marketplace/actions/problem-matcher-for-markdownlint-cli
+      - name: Enable showing issue in PRs
+        uses: xt0rted/markdownlint-problem-matcher@v1
+
+      - name: Check markdown with CLI2
+        run: markdownlint-cli2
+
+  remark:
+    name: 'QA Markdown'
+    runs-on: ubuntu-latest
+
+    # Don't run the cronjob in this workflow on forks.
+    if: github.event_name != 'schedule' || (github.event_name == 'schedule' && github.repository_owner == 'Yoast')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Set up node and enable caching of dependencies
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      # To make the command available on CLI, it needs to be installed globally.
+      - name: Install Remark CLI globally
+        run: npm install --global remark-cli --foreground-scripts true --fund false
+
+      # To allow for creating a custom config which references rules which are included
+      # in the presets, without having to install all rules individually, a local install
+      # works best (and installing the presets in the first place, of course).
+      #
+      # Note: the first group of packages are all part of the mono "Remark lint" repo.
+      # The second group of packages (heading-whitespace and down) are additional
+      # "external" rules/plugins.
+      - name: Install Remark rules locally
+        run: >
+          npm install --foreground-scripts true --fund false
+          remark-lint
+          remark-gfm
+          remark-preset-lint-consistent
+          remark-preset-lint-recommended
+          remark-preset-lint-markdown-style-guide
+          remark-lint-checkbox-content-indent
+          remark-lint-linebreak-style
+          remark-lint-no-empty-url
+          remark-lint-no-heading-like-paragraph
+          remark-lint-no-reference-like-url
+          remark-lint-no-unneeded-full-reference-image
+          remark-lint-no-unneeded-full-reference-link
+          remark-lint-strikethrough-marker
+          remark-lint-heading-whitespace
+          remark-lint-list-item-punctuation
+          remark-lint-match-punctuation
+          remark-lint-no-hr-after-heading
+          remark-lint-are-links-valid-alive
+          remark-lint-are-links-valid-duplicate
+          remark-validate-links
+
+      - name: Run Remark-lint
+        run: remark . --frail
+
+      # @link https://github.com/reviewdog/action-remark-lint
+      - name: Show Remark-lint annotations in PR
+        if: ${{ failure() && github.event_name == 'pull_request' }}
+        uses: reviewdog/action-remark-lint@v5
+        with:
+          fail_on_error: true
+          install_deps: false
+          level: info
+          reporter: github-pr-check

.gitignore

@@ -1,4 +1,5 @@
 /composer.lock
+node_modules/
 vendor/
 /.phpcs.xml
 /phpcs.xml

.markdownlint-cli2.yaml

@@ -0,0 +1,107 @@
+#
+# Configuration file for MarkdownLint-CLI2.
+#
+# Example file with all options:
+# https://github.com/DavidAnson/markdownlint-cli2/blob/main/test/markdownlint-cli2-yaml-example/.markdownlint-cli2.yaml
+#
+
+# Do not fix any fixable errors.
+fix: false
+
+# Define glob expressions to use (only valid at root).
+globs:
+  - "**/*.md"
+  - ".github/**/*.md"
+
+# Define glob expressions to ignore.
+ignores:
+  - "node_modules/"
+  - "vendor/"
+
+# Disable inline config comments.
+noInlineConfig: true
+
+# Disable progress on stdout (only valid at root).
+noProgress: false
+
+# Adjust the configuration for some built-in rules.
+# For full information on the options and defaults, see:
+# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
+config:
+  ######################
+  # Disable a few rules.
+  ######################
+  # MD003/heading-style/header-style - Heading style.
+  MD003: false
+  # MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines.
+  MD031: false
+  # MD032/blanks-around-lists - Lists should be surrounded by blank lines.
+  MD032: false
+
+  ##############################
+  # Customize a few other rules.
+  ##############################
+  # MD004/ul-style - Unordered list style.
+  MD004:
+    # List style - each level has a different, but consistent symbol.
+    style: "sublist"
+
+  # MD007/ul-indent - Unordered list indentation.
+  MD007:
+    indent: 4
+    # Whether to indent the first level of the list.
+    start_indented: false
+
+  # MD012/no-multiple-blanks - Multiple consecutive blank lines.
+  MD012:
+    maximum: 2
+
+  # MD013/line-length - Line length.
+  MD013:
+    # Number of characters. No need for being too fussy.
+    line_length: 1000
+    # Number of characters for headings.
+    heading_line_length: 105
+    # Number of characters for code blocks.
+    code_block_line_length: 100
+    # Stern length checking (applies to tables, code blocks etc which have their own max line length).
+    stern: true
+
+  # MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
+  MD022:
+    # Blank lines below heading
+    lines_below: false
+
+  # MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content.
+  MD024:
+    # Only check sibling headings.
+    siblings_only: true
+
+  # MD033/no-inline-html - Inline HTML.
+  MD033:
+    # Allowed elements.
+    allowed_elements:
+      - br
+
+  # MD044/proper-names - Proper names should have the correct capitalization.
+  MD044:
+    # List of proper names.
+    names: ["PHPUnit"]
+    # Include code blocks.
+    code_blocks: false
+
+  # MD046/code-block-style - Code block style
+  MD046:
+    style: "fenced"
+
+  # MD048/code-fence-style - Code fence style
+  MD048:
+    style: "backtick"
+
+  # MD049/emphasis-style - Emphasis style should be consistent
+  MD049:
+    style: "underscore"
+
+  # MD050/strong-style - Strong style should be consistent
+  MD050:
+    style: "asterisk"

.remarkignore

@@ -0,0 +1,5 @@
+# Ignore rules for Remark.
+# Docs: https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/ignore.md
+
+/node_modules/
+/vendor/

.remarkrc

@@ -0,0 +1,35 @@
+{
+  "plugins": [
+    "remark-gfm",
+    ["remark-lint-checkbox-character-style", "consistent"],
+    ["remark-lint-checkbox-content-indent", "consistent"],
+    "remark-lint-definition-spacing",
+    "remark-lint-file-extension",
+    ["remark-lint-linebreak-style", "unix"],
+    ["remark-lint-link-title-style", "\""],
+    ["remark-lint-ordered-list-marker-style", "."],
+    "remark-lint-no-duplicate-definitions",
+    "remark-lint-no-empty-url",
+    "remark-lint-no-file-name-consecutive-dashes",
+    "remark-lint-no-file-name-irregular-characters",
+    "remark-lint-no-file-name-outer-dashes",
+    "remark-lint-no-heading-like-paragraph",
+    "remark-lint-no-literal-urls",
+    "remark-lint-no-reference-like-url",
+    "remark-lint-no-shortcut-reference-image",
+    "remark-lint-no-table-indentation",
+    "remark-lint-no-undefined-references",
+    "remark-lint-no-unneeded-full-reference-image",
+    "remark-lint-no-unneeded-full-reference-link",
+    "remark-lint-no-unused-definitions",
+    ["remark-lint-strikethrough-marker", "~~"],
+    ["remark-lint-table-cell-padding", "consistent"],
+    "remark-lint-heading-whitespace",
+    "remark-lint-list-item-punctuation",
+    "remark-lint-match-punctuation",
+    "remark-lint-no-hr-after-heading",
+    "remark-lint-are-links-valid-alive",
+    "remark-lint-are-links-valid-duplicate",
+    "remark-validate-links"
+  ]
+}

README.md

@@ -617,7 +617,7 @@ class MyTest extends XTestCase {
 ### TestListener
 
 The method signatures in the PHPUnit `TestListener` interface have changed a number of times across versions.
-Additionally, the use of the TestListener principle has been deprecated in PHPUnit 7 in favour of using the [TestRunner hook interfaces](https://phpunit.readthedocs.io/en/9.3/extending-phpunit.html#extending-the-testrunner).
+Additionally, the use of the TestListener principle has been deprecated in PHPUnit 7 in favour of using the [TestRunner hook interfaces](https://docs.phpunit.de/en/7.5/extending-phpunit.html#extending-the-testrunner).
 
 > Note: while deprecated in PHPUnit 7, the TestListener interface has not yet been removed and is still supported in PHPUnit 9.x.
 
@@ -687,9 +687,11 @@ For frequently used, removed PHPUnit functionality, "helpers" may be provided. T
 
 | PHPUnit | Removed               | Issue     | Remarks                |
 |---------|-----------------------|-----------|------------------------|
-| 9.0.0   | `assertArraySubset()` | [#1](https://github.com/Yoast/PHPUnit-Polyfills/issues/1) | The [`dms/phpunit-arraysubset-asserts`](https://packagist.org/packages/dms/phpunit-arraysubset-asserts) package polyfills this functionality.<br/>As of [version 0.3.0](https://github.com/rdohms/phpunit-arraysubset-asserts/releases/tag/v0.3.0) this package can be installed in combination with PHP 5.4 - current and PHPUnit 4.8.36/5.7.21 - current.<br/>Alternatively, tests can be refactored using the patterns outlined in [issue #1](https://github.com/Yoast/PHPUnit-Polyfills/issues/1).
-| 9.0.0   | `assertAttribute*()`  | [#2](https://github.com/Yoast/PHPUnit-Polyfills/issues/2) | Refactor the tests to not directly test private/protected properties.<br/>As an interim solution, the [`Yoast\PHPUnitPolyfills\Helpers\AssertAttributeHelper`](#yoastphpunitpolyfillshelpersassertattributehelper) trait is available.
+| 9.0.0   | `assertArraySubset()` | [#1][issue #1] | The [`dms/phpunit-arraysubset-asserts`](https://packagist.org/packages/dms/phpunit-arraysubset-asserts) package polyfills this functionality.<br/>As of [version 0.3.0](https://github.com/rdohms/phpunit-arraysubset-asserts/releases/tag/v0.3.0) this package can be installed in combination with PHP 5.4 - current and PHPUnit 4.8.36/5.7.21 - current.<br/>Alternatively, tests can be refactored using the patterns outlined in [issue #1]. |
+| 9.0.0   | `assertAttribute*()`  | [#2][issue #2] | Refactor the tests to not directly test private/protected properties.<br/>As an interim solution, the [`Yoast\PHPUnitPolyfills\Helpers\AssertAttributeHelper`](#yoastphpunitpolyfillshelpersassertattributehelper) trait is available. |
 
+[issue #1]: https://github.com/Yoast/PHPUnit-Polyfills/issues/1
+[issue #2]: https://github.com/Yoast/PHPUnit-Polyfills/issues/2
 
 ### Q: Can this library be used when the tests are being run via a PHPUnit Phar file ?
 
@@ -701,7 +703,7 @@ In that case, make sure that the `phpunitpolyfills-autoload.php` file is explici
 
 ### Q: How do I run my tests when the library is installed via the GitHub Actions `setup-php` action ?
 
-As of [shivammathur/setup-php](https://github.com/shivammathur/setup-php) version [2.15.0](https://github.com/shivammathur/setup-php/releases/tag/2.15.0), the PHPUnit Polyfills are available as one of the tools which can be installed directly by the Setup-PHP GitHub action.
+As of [shivammathur/setup-php](https://github.com/shivammathur/setup-php) version [2.15.0](https://github.com/shivammathur/setup-php/releases/tag/2.15.0), the PHPUnit Polyfills are available as one of the tools which can be installed directly by the Setup-PHP GitHub action runner.
 
 ```yaml
 - name: Setup PHP with tools
@@ -746,12 +748,14 @@ $versionRequirement = '1.0.1';
 if ( defined( '\Yoast\PHPUnitPolyfills\Autoload::VERSION' ) === false
     || version_compare( \Yoast\PHPUnitPolyfills\Autoload::VERSION, $versionRequirement, '<' )
 ) {
-    echo 'Error: Version mismatch detected for the PHPUnit Polyfills. Please ensure that PHPUnit Polyfills ',
-        $versionRequirement, ' or higher is loaded.', PHP_EOL;
+    echo 'Error: Version mismatch detected for the PHPUnit Polyfills.',
+        ' Please ensure that PHPUnit Polyfills ', $versionRequirement,
+        ' or higher is loaded.', PHP_EOL;
     exit(1);
 } else {
     echo 'Error: Please run `composer update -W` before running the tests.' . PHP_EOL;
-    echo 'You can still use a PHPUnit phar to run them, but the dependencies do need to be installed.', PHP_EOL;
+    echo 'You can still use a PHPUnit phar to run them,',
+        ' but the dependencies do need to be installed.', PHP_EOL;
     exit(1);
 }
 ```
@@ -766,4 +770,4 @@ If you are unsure whether the changes you are proposing would be welcome, please
 
 License
 -------
-This code is released under the [BSD-3-Clause License](https://opensource.org/licenses/BSD-3-Clause).
+This code is released under the [BSD-3-Clause License](LICENSE).