diff --git a/.gitattributes b/.gitattributes index 074a6f2..67ccd8e 100644 --- a/.gitattributes +++ b/.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 diff --git a/.github/RELEASE-CHECKLIST.md b/.github/RELEASE-CHECKLIST.md index c0d7fca..cfc5ca0 100644 --- a/.github/RELEASE-CHECKLIST.md +++ b/.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. diff --git a/.github/workflows/markdown.yml b/.github/workflows/markdown.yml new file mode 100644 index 0000000..5f0fcd5 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index be62b84..179ad62 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /composer.lock +node_modules/ vendor/ /.phpcs.xml /phpcs.xml diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..0255a55 --- /dev/null +++ b/.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" diff --git a/.remarkignore b/.remarkignore new file mode 100644 index 0000000..6718a0b --- /dev/null +++ b/.remarkignore @@ -0,0 +1,5 @@ +# Ignore rules for Remark. +# Docs: https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/ignore.md + +/node_modules/ +/vendor/ diff --git a/.remarkrc b/.remarkrc new file mode 100644 index 0000000..e54bb8b --- /dev/null +++ b/.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" + ] +} diff --git a/README.md b/README.md index 3180f5c..7dc2c66 100644 --- a/README.md +++ b/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.
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.
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.
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.
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.
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.
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).