diff --git a/.github/RELEASE-CHECKLIST.md b/.github/RELEASE-CHECKLIST.md new file mode 100644 index 0000000..c0d7fca --- /dev/null +++ b/.github/RELEASE-CHECKLIST.md @@ -0,0 +1,31 @@ +Template to use for release PRs from `develop` to `main` +=========================================================== + +Title: Release version x.x.x + +### 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: +- [ ] 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. +- [ ] Make sure all CI builds are green. +- [ ] Tag the release (careful, GH defaults to `develop`!). +- [ ] Create a release from the tag (careful, GH defaults to `develop`!) & copy & paste the changelog to it. + Make sure to copy the links to the issues and the links to the GH usernames from the bottom of the changelog! +- [ ] Close the milestone. +- [ ] 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: +- [ ] Tweet about the release. + + +--- + +Additional actions to take, not part of the release checklist: +- [ ] Post a link to the release in the Yoast Slack. +- [ ] Update the dependency version constraints for WP Test Utils. diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 4666c00..370f2d4 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -71,6 +71,7 @@ jobs: uses: shivammathur/setup-php@v2 with: php-version: ${{ matrix.php }} + ini-values: error_reporting=E_ALL, display_errors=On coverage: none - name: 'Composer: set PHPUnit version for tests' diff --git a/CHANGELOG.md b/CHANGELOG.md index dc7e44c..23e54bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,13 +9,27 @@ This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses _Nothing yet._ +## [1.0.1] - 2021-08-09 + +### Added +* The `Yoast\PHPUnitPolyfills\Autoload` class now contains a `VERSION` constant. Issue [#46], PR [#47], props [Pascal Birchler] for the suggestion. + This version constant can be used by (complex) test setups to verify that the PHPUnit Polyfills which will be loaded, comply with the version requirements for the test suite. + +### Changed +* Minor documentation updates. [#43] + +[#43]: https://github.com/Yoast/PHPUnit-Polyfills/pull/43 +[#46]: https://github.com/Yoast/PHPUnit-Polyfills/issues/46 +[#47]: https://github.com/Yoast/PHPUnit-Polyfills/pull/47 + + ## [1.0.0] - 2021-06-21 ### Added * `Yoast\PHPUnitPolyfills\Polyfills\AssertClosedResource` trait to polyfill the `Assert::assertIsClosedResource()` and `Assert::assertIsNotClosedResource()` methods as introduced in PHPUnit 9.3.0. PR [#27]. * `Yoast\PHPUnitPolyfills\Polyfills\AssertObjectEquals` trait to polyfill the `Assert::assertObjectEquals()` method as introduced in PHPUnit 9.4.0. PR [#38]. The behaviour of the polyfill closely matches the PHPUnit native implementation, but is not 100% the same. - Most notably, the polyfill will check the type of the returned value from the comparator method instead of the enforcing a return type declaration of the comparator method. + Most notably, the polyfill will check the type of the returned value from the comparator method instead of enforcing a return type declaration for the comparator method. * `Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations` trait to polyfill the `Assert::equalToCanonicalizing()`, `Assert::equalToIgnoringCase()` and `Assert::equalToWithDelta()` methods as introduced in PHPUnit 9.0.0. PR [#28], props [Marc Siegrist]. * Polyfills for the PHP native `Error` and `TypeError` classes as introduced in PHP 7.0. PR [#36]. * README: FAQ section covering functionality removed from PHPUnit and usage with a Phar. @@ -67,6 +81,7 @@ Initial release. [Unreleased]: https://github.com/Yoast/PHPUnit-Polyfills/compare/main...HEAD +[1.0.1]: https://github.com/Yoast/PHPUnit-Polyfills/compare/1.0.0...1.0.1 [1.0.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/0.2.0...1.0.0 [0.2.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/0.1.0...0.2.0 [0.1.0]: https://github.com/Yoast/PHPUnit-Polyfills/compare/e8f8b7a73737aa9a5974bd9c73d2bd8d09f69873...0.1.0 @@ -74,3 +89,4 @@ Initial release. [Gary Jones]: https://github.com/GaryJones [Marc Siegrist]: https://github.com/mergeMarc [Mark Baker]: https://github.com/MarkBaker +[Pascal Birchler]: https://github.com/swissspidy diff --git a/README.md b/README.md index f78a1f6..85d40d5 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,7 @@ For the polyfills to work, a test class is **required** to be a (grand-)child of If your library still needs to support PHP < 5.6 and therefore needs PHPUnit 4 for testing, there are a few caveats when using the traits stand-alone as we then enter "double-polyfill" territory. -To prevent "conflicting method names" errors when a trait is `use`d multiple times in a class, the traits offered here do not attempt to solve this. +To prevent _"conflicting method names"_ errors when a trait is `use`d multiple times in a class, the traits offered here do not attempt to solve this. You will need to make sure to `use` any additional traits needed for the polyfills to work. @@ -433,7 +433,7 @@ if ( self::shouldClosedResourceAssertionBeSkipped( $actual ) === false ) { } ``` -> :point_right: While this polyfill is tested extensively, testing for these kind of bugs exhaustively is _hard_. +> :point_right: While this polyfill is tested extensively, testing for these kind of bugs _exhaustively_ is _hard_. > Please [report any bugs](https://github.com/Yoast/PHPUnit-Polyfills/issues/new/choose) found and include a clear code sample to reproduce the issue. #### PHPUnit < 9.4.0: `Yoast\PHPUnitPolyfills\Polyfills\AssertObjectEquals` @@ -441,19 +441,20 @@ if ( self::shouldClosedResourceAssertionBeSkipped( $actual ) === false ) { Polyfills the [`Assert::assertObjectEquals()`] method to verify two (value) objects are considered equal. This assertion expects an object to contain a comparator method in the object itself. This comparator method is subsequently called to verify the "equalness" of the objects. -The `assertObjectEquals() assertion was introduced in PHPUnit 9.4.0. +The `assertObjectEquals()` assertion was introduced in PHPUnit 9.4.0. -> :info: Due to [limitations in how this assertion is implemented in PHPUnit] itself, it is currently not possible to create a single comparator method which will be compatible with both PHP < 7.0 and PHP 7.0 or higher. +> :information_source: Due to [limitations in how this assertion is implemented in PHPUnit] itself, it is currently not possible to create a single comparator method which will be compatible with both PHP < 7.0 and PHP 7.0 or higher. > > In effect two declarations of the same object would be needed to be compatible with PHP < 7.0 and PHP 7.0 and higher and still allow for testing the object using the `assertObjectEquals()` assertion. > > Due to this limitation, it is recommended to only use this assertion if the minimum supported PHP version of a project is PHP 7.0 or higher; or if the project does not run its tests on PHPUnit >= 9.4.0. +> +> The implementation of this assertion in the Polyfills is PHP cross-version compatible. [limitations in how this assertion is implemented in PHPUnit]: https://github.com/sebastianbergmann/phpunit/issues/4707 - +[`Assert::assertObjectEquals()`]: https://phpunit.readthedocs.io/en/stable/assertions.html#assertobjectequals + ### Helper traits @@ -687,6 +688,30 @@ Yes, this package can also be used when running tests via a PHPUnit Phar file. In that case, make sure that the `phpunitpolyfills-autoload.php` file is explicitly `require`d in the test bootstrap file. (Not necessary when the Composer `vendor/autoload.php` file is used as, or `require`d in, the test bootstrap.) +### Q: How can I verify the version used of the PHPUnit Polyfills library ? + +For complex test setups, like when the Polyfills are provided via a test suite dependency, or may already be loaded via an overarching project, it can be useful to be able to check that a version of the package is used which complies with the requirements for your test suite. + +As of version 1.0.1, the PHPUnit Polyfills `Autoload` class contains a version number which can be used for this purpose. + +Typically such a check would be done in the test suite bootstrap file and could look something like this: +```php +$versionRequirement = '1.0.1'; +if ( class_exists( '\Yoast\PHPUnitPolyfills\Autoload' ) === false ) { + require_once `vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php`; +} elseif ( 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; + exit(1); +} else { + echo 'Error: Please run `composer update` 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; + exit(1); +} +``` + Contributing ------------ diff --git a/phpunitpolyfills-autoload.php b/phpunitpolyfills-autoload.php index 1a66453..42704a8 100644 --- a/phpunitpolyfills-autoload.php +++ b/phpunitpolyfills-autoload.php @@ -11,6 +11,13 @@ */ class Autoload { + /** + * Version number. + * + * @var string + */ + const VERSION = '1.0.1'; + /** * Loads a class. *