yoast / phpunit-polyfills
Set of polyfills for changed PHPUnit functionality to allow for creating PHPUnit cross-version compatible tests
Installs: 22 858 680
Dependents: 666
Suggesters: 1
Security: 0
Stars: 173
Watchers: 18
Forks: 13
Open Issues: 5
Requires
- php: >=7.0
- phpunit/phpunit: ^6.4.4 || ^7.0 || ^8.0 || ^9.0 || ^11.0
Requires (Dev)
- php-parallel-lint/php-console-highlighter: ^1.0.0
- php-parallel-lint/php-parallel-lint: ^1.4.0
- yoast/yoastcs: ^3.1.0
- 3.x-dev
- dev-main / 3.x-dev
- 3.0.0
- 2.x-dev
- 2.0.2
- 2.0.1
- 2.0.0
- 1.x-dev
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 0.2.0
- 0.1.0
- dev-feature/phpstan-2.0-update
- dev-feature/README-fix-broken-links
- dev-feature/phpunit-10-cross-version-testlistener-implementation
- dev-feature/split-tests
- dev-feature/tests-expand-testlistener-test
- dev-feature/ghactions-add-exakat-workflow
This package is auto-updated.
Last update: 2024-12-08 07:43:37 UTC
README
Set of polyfills for changed PHPUnit functionality to allow for creating PHPUnit cross-version compatible tests.
- Requirements
- Installation
- Why use the PHPUnit Polyfills?
- Using this library
- Features
- Frequently Asked Questions
- Contributing
- License
Requirements
- PHP 7.0 or higher.
- PHPUnit 6.4 - 9.x and 11.x (automatically required via Composer).
Installation
To install this package, run:
composer require --dev yoast/phpunit-polyfills:"^3.0"
To update this package, run:
composer update --dev yoast/phpunit-polyfills --with-dependencies
Autoloading
Make sure to:
- Either use the Composer
vendor/autoload.php
file as your test bootstrap file; - Or require the
vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php
file in your test bootstrap.
Why use the PHPUnit Polyfills?
This library is set up to allow for creating PHPUnit cross-version compatible tests by offering a number of polyfills for functionality which was introduced, split up or renamed in PHPUnit.
Write your tests for PHPUnit 11.x and run them on PHPUnit 6.4 - 11.x
The polyfills have been setup to allow tests to be forward-compatible. What that means is, that your tests can use the assertions supported by the latest PHPUnit version, even when running on older PHPUnit versions.
This puts the burden of upgrading to use the syntax of newer PHPUnit versions at the point when you want to start running your tests on a newer version.
By doing so, dropping support for an older PHPUnit version becomes as straight-forward as removing it from the version constraint in your composer.json
file.
PHPUnit support
- Releases in the
1.x
series of the PHPUnit Polyfills support PHPUnit 4.8 - 9.x. - Releases in the
2.x
series of the PHPUnit Polyfills support PHPUnit 5.7 - 10.x. - Releases in the
3.x
series of the PHPUnit Polyfills support PHPUnit 6.4 - 11.x (but don't support running tests on PHPUnit 10).
Please keep in mind that the PHPUnit Polyfills provide forward-compatibility. This means that features which PHPUnit no longer supports in PHPUnit 10.x, like expecting PHP deprecation notices or warnings, will not be supported in the PHPUnit Polyfills 2.x series and features not supported in PHPUnit 11.x, will not be supported in the PHPUnit Polyfills 3.x series.
Please refer to the PHPUnit 10 release notification/PHPUnit 10 changelog and the PHPUnit 11 release notification/PHPUnit 11 changelog to inform your decision on whether or not to upgrade (yet).
Using this library
Each of the polyfills and helpers has been setup as a trait and can be imported and use
d in any test file which extends the PHPUnit native TestCase
class.
If the polyfill is not needed for the particular PHPUnit version on which the tests are being run, the autoloader will automatically load an empty trait with that same name, so you can safely use these traits in tests which need to be PHPUnit cross-version compatible.
<?php namespace Vendor\YourPackage\Tests; use PHPUnit\Framework\TestCase; use Yoast\PHPUnitPolyfills\Polyfills\AssertIsType; class FooTest extends TestCase { use AssertIsType; public function testSomething() { $this->assertIsBool( $maybeBool ); self::assertIsNotIterable( $maybeIterable ); } }
Alternatively, you can use one of the TestCase
classes provided by this library instead of using the PHPUnit native TestCase
class.
In that case, all polyfills and helpers will be available whenever needed.
<?php namespace Vendor\YourPackage\Tests; use Yoast\PHPUnitPolyfills\TestCases\TestCase; class FooTest extends TestCase { public function testSomething() { $this->assertIsBool( $maybeBool ); self::assertMatchesRegularExpression( $pattern, $string, $message ); } }
Supported ways of calling the assertions
By default, PHPUnit supports four ways of calling assertions:
- As a method in the
TestCase
class -$this->assertSomething()
. - Statically as a method in the
TestCase
class -self/static/parent::assertSomething()
. - Statically as a method of the
Assert
class -Assert::assertSomething()
. - As a global function -
assertSomething()
.
The polyfills in this library support the first two ways of calling the assertions as those are the most commonly used type of assertion calls.
For the polyfills to work, a test class is required to be a (grand-)child of the PHPUnit native TestCase
class.
Use with PHPUnit < 7.5.0
If your library still needs to support PHP < 7.1 and therefore needs PHPUnit < 7 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.
You will need to make sure to use
any additional traits needed for the polyfills to work.
Note: this only applies to the stand-alone use of the traits. The TestCase
classes provided by this library already take care of this automatically.
Code example for a test using the AssertIgnoringLineEndings
trait, which needs to be able to run on PHPUnit 6.4:
<?php namespace Vendor\YourPackage\Tests; use PHPUnit\Framework\TestCase; use Yoast\PHPUnitPolyfills\Polyfills\AssertIgnoringLineEndings; use Yoast\PHPUnitPolyfills\Polyfills\AssertStringContains; class FooTest extends TestCase { use AssertIgnoringLineEndings; use AssertStringContains; public function testSomething() { $this->assertStringContainsStringIgnoringLineEndings( "something\nelse", "this is something\r\nelse" ); } }
Features
Polyfill traits
PHPUnit < 7.5.0: Yoast\PHPUnitPolyfills\Polyfills\AssertIsType
Polyfills the following methods:
These methods were introduced in PHPUnit 7.5.0 as alternatives to the Assert::assertInternalType()
and Assert::assertNotInternalType()
methods, which were soft deprecated in PHPUnit 7.5.0, hard deprecated (warning) in PHPUnit 8.0.0 and removed in PHPUnit 9.0.0.
PHPUnit < 7.5.0: Yoast\PHPUnitPolyfills\Polyfills\AssertStringContains
Polyfills the following methods:
These methods were introduced in PHPUnit 7.5.0 as alternatives to using Assert::assertContains()
and Assert::assertNotContains()
with string haystacks. Passing string haystacks to these methods was soft deprecated in PHPUnit 7.5.0, hard deprecated (warning) in PHPUnit 8.0.0 and removed in PHPUnit 9.0.0.
PHPUnit < 7.5.0: Yoast\PHPUnitPolyfills\Polyfills\AssertEqualsSpecializations
Polyfills the following methods:
These methods were introduced in PHPUnit 7.5.0 as alternatives to using Assert::assertEquals()
and Assert::assertNotEquals()
with these optional parameters. Passing the respective optional parameters to these methods was soft deprecated in PHPUnit 7.5.0, hard deprecated (warning) in PHPUnit 8.0.0 and removed in PHPUnit 9.0.0.
PHPUnit < 8.4.0: Yoast\PHPUnitPolyfills\Polyfills\ExpectExceptionMessageMatches
Polyfills the TestCase::expectExceptionMessageMatches()
method.
This method was introduced in PHPUnit 8.4.0 to improve the name of the TestCase::expectExceptionMessageRegExp()
method.
The TestCase::expectExceptionMessageRegExp()
method was soft deprecated in PHPUnit 8.4.0, hard deprecated (warning) in PHPUnit 8.5.3 and removed in PHPUnit 9.0.0.
PHPUnit < 8.5.0: Yoast\PHPUnitPolyfills\Polyfills\AssertFileEqualsSpecializations
Polyfills the following methods:
These methods were introduced in PHPUnit 8.5.0 as alternatives to using Assert::assertFileEquals()
and Assert::assertFileNotEquals()
with these optional parameters. Passing the respective optional parameters to these methods was hard deprecated in PHPUnit 8.5.0 and removed in PHPUnit 9.0.0.
PHPUnit < 9.0.0: Yoast\PHPUnitPolyfills\Polyfills\EqualToSpecializations
Polyfills the following methods:
These methods, which are typically used to verify parameters passed to Mock Objects, were introduced in PHPUnit 9.0.0 as alternatives to using Assert::EqualTo()
with these optional parameters. Support for passing the respective optional parameters to Assert::EqualTo()
was removed in PHPUnit 9.0.0.
PHPUnit < 9.1.0: Yoast\PHPUnitPolyfills\Polyfills\AssertionRenames
Polyfills the following renamed methods:
Assert::assertIsNotReadable()
, introduced as alternative forAssert::assertNotIsReadable()
.Assert::assertIsNotWritable()
, introduced as alternative forAssert::assertNotIsWritable()
.Assert::assertDirectoryDoesNotExist()
, introduced as alternative forAssert::assertDirectoryNotExists()
.Assert::assertDirectoryIsNotReadable()
, introduced as alternative forAssert::assertDirectoryNotIsReadable()
.Assert::assertDirectoryIsNotWritable()
, introduced as alternative forAssert::assertDirectoryNotIsWritable()
.Assert::assertFileDoesNotExist()
, introduced as alternative forAssert::assertFileNotExists()
.Assert::assertFileIsNotReadable()
, introduced as alternative forAssert::assertFileNotIsReadable()
.Assert::assertFileIsNotWritable()
, introduced as alternative forAssert::assertFileNotIsWritable()
.Assert::assertMatchesRegularExpression()
, introduced as alternative forAssert::assertRegExp()
.Assert::assertDoesNotMatchRegularExpression()
, introduced as alternative forAssert::assertNotRegExp()
.
These methods were introduced in PHPUnit 9.1.0. The original methods these new methods replace were hard deprecated in PHPUnit 9.1.0 and removed in PHPUnit 10.0.0.
PHPUnit < 9.3.0: Yoast\PHPUnitPolyfills\Polyfills\AssertClosedResource
Polyfills the following methods:
These methods were introduced in PHPUnit 9.3.0.
Additionally, this trait contains a helper method shouldClosedResourceAssertionBeSkipped()
.
Due to some bugs in PHP itself, the "is closed resource" determination cannot always be done reliably, most notably for the libxml
extension.
This helper function can determine whether or not the current "value under test" in combination with the PHP version on which the test is being run is affected by these bugs.
â ī¸ The PHPUnit native implementation of these assertions is also affected by these bugs! The
shouldClosedResourceAssertionBeSkipped()
helper method is therefore available cross-version.
Usage examples:
// Example: skipping the test completely. if ( $this->shouldClosedResourceAssertionBeSkipped( $actual ) === true ) { $this->markTestSkipped('assertIs[Not]ClosedResource() cannot determine whether this resource is' . ' open or closed due to bugs in PHP (PHP ' . \PHP_VERSION . ').'); } // Example: selectively skipping the assertion. if ( self::shouldClosedResourceAssertionBeSkipped( $actual ) === false ) { $this->assertIsClosedResource( $actual ); }
đ While this polyfill is tested extensively, testing for these kind of bugs exhaustively is hard. Please report any bugs found and include a clear code sample to reproduce the issue.
PHPUnit < 9.4.0: Yoast\PHPUnitPolyfills\Polyfills\AssertObjectEquals
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.
âšī¸ In PHPUnit Polyfills 1.x and 2.x, the polyfill for this assertion had some limitations. These limitations are no longer present in PHPUnit Polyfills 3.x and the assertion now matches the PHPUnit native implementation.
PHPUnit < 10.0.0: Yoast\PHPUnitPolyfills\Polyfills\AssertIgnoringLineEndings
Polyfills the following methods:
These methods were introduced in PHPUnit 10.0.0.
PHPUnit < 10.0.0: Yoast\PHPUnitPolyfills\Polyfills\AssertIsList
Polyfills the following method:
This method was introduced in PHPUnit 10.0.0.
PHPUnit < 10.1.0: Yoast\PHPUnitPolyfills\Polyfills\AssertObjectProperty
Polyfills the following methods:
These methods were introduced in PHPUnit 10.1.0 as alternatives to the Assert::assertObjectHasAttribute()
and Assert::assertObjectNotHasAttribute()
methods, which were hard deprecated (warning) in PHPUnit 9.6.1 and removed in PHPUnit 10.0.0.
These methods were later backported to the PHPUnit 9 branch and included in the PHPUnit 9.6.11 release.
PHPUnit < 11.0.0: Yoast\PHPUnitPolyfills\Polyfills\AssertArrayWithListKeys
Polyfills the following methods:
These methods were introduced in PHPUnit 11.0.0.
This functionality resembles the functionality previously offered by the Assert::assertArraySubset()
assertion, which was removed in PHPUnit 9.0.0, but with higher precision.
Refactoring tests which still use Assert::assertArraySubset()
to use the new assertions should be considered as an upgrade path.
PHPUnit < 11.0.0: Yoast\PHPUnitPolyfills\Polyfills\ExpectUserDeprecation
These methods were introduced in PHPUnit 11.0.0.
This functionality resembles the functionality previously offered by the TestCase::expectDeprecationMessage()
and TestCase::expectDeprecationMessageMatches()
methods, which were removed in PHPUnit 10.0.0.
The polyfill use the old methods under the hood for PHPUnit <= 9, however, there are some pertinent differences in behaviour between the old and the new methods, which users of the polyfill should be aware of.
Please keep these differences in mind when writing tests using the expectUserDeprecationMessage*()
methods.
Note: on PHPUnit 9.5.x, when using the expectUserDeprecationMessage*()
expectations, a "Expecting E_DEPRECATED and E_USER_DEPRECATED is deprecated and will no longer be possible in PHPUnit 10." deprecation will be shown in the test output.
As long at the actual test uses the expectUserDeprecationMessage*()
expectations, this depreation message can be safely ignored.
âšī¸ Important: when using the
expectUserDeprecationMessage*()
expectation(s) in a test, the test should be annotated with a#[IgnoreDeprecations]
attribute.
PHPUnit < 11.2.0: Yoast\PHPUnitPolyfills\Polyfills\AssertObjectNotEquals
Polyfills the Assert::assertObjectNotEquals()
method to verify two (value) objects are not considered equal.
This is the sister-method to the PHPUnit 9.4+ Assert::assertObjectEquals()
method.
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 assertObjectNotEquals()
assertion was introduced in PHPUnit 11.2.0.
TestCases
PHPUnit 8.0.0 introduced a void
return type declaration to the "fixture" methods - setUpBeforeClass()
, setUp()
, tearDown()
and tearDownAfterClass()
.
As the void
return type was not introduced until PHP 7.1, this makes it more difficult to create cross-version compatible tests when using fixtures, due to signature mismatches.
This library contains two basic TestCase
options to overcome this issue.
Option 1: Yoast\PHPUnitPolyfills\TestCases\TestCase
This TestCase
overcomes the signature mismatch by having two versions. The correct one will be loaded depending on the PHPUnit version being used.
When using this TestCase
, if an individual test, or another TestCase
which extends this TestCase
, needs to overload any of the "fixture" methods, it should do so by using a snake_case variant of the original fixture method name, i.e. set_up_before_class()
, set_up()
, assert_pre_conditions()
, assert_post_conditions()
, tear_down()
and tear_down_after_class()
.
The snake_case methods will automatically be called by PHPUnit.
IMPORTANT: The snake_case methods should not call the PHPUnit parent, i.e. do not use
parent::setUp()
from within an overloadedset_up()
method. If necessary, DO callparent::set_up()
.
use Yoast\PHPUnitPolyfills\TestCases\TestCase; class MyTest extends TestCase { public static function set_up_before_class() { parent::set_up_before_class(); // Set up a database connection or other fixture which needs to be available. } protected function set_up() { parent::set_up(); // Set up function mocks which need to be available for all tests in this class. } protected function assert_pre_conditions() { parent::assert_pre_conditions(); // Perform assertions shared by all tests of a test case (before the test). } protected function assert_post_conditions() { // Performs assertions shared by all tests of a test case (after the test). parent::assert_post_conditions(); } protected function tear_down() { // Any clean up needed related to `set_up()`. parent::tear_down(); } public static function tear_down_after_class() { // Close database connection and other clean up related to `set_up_before_class()`. parent::tear_down_after_class(); } }
Option 2: Yoast\PHPUnitPolyfills\TestCases\XTestCase
This TestCase
overcomes the signature mismatch by using the PHPUnit @before[Class]
and @after[Class]
annotations in combination with different methods names, i.e. setUpFixturesBeforeClass()
, setUpFixtures()
, tearDownFixtures()
and tearDownFixturesAfterClass()
.
When using this TestCase, overloaded fixture methods need to use the @beforeClass
, @before
, @after
and @afterClass
annotations.
The naming of the overloaded methods is open as long as the method names don't conflict with the PHPUnit native method names.
use Yoast\PHPUnitPolyfills\TestCases\XTestCase; class MyTest extends XTestCase { /** * @beforeClass */ public static function setUpFixturesBeforeClass() { parent::setUpFixturesBeforeClass(); // Set up a database connection or other fixture which needs to be available. } /** * @before */ protected function setUpFixtures() { parent::setUpFixtures(); // Set up function mocks which need to be available for all tests in this class. } /** * @after */ protected function tearDownFixtures() { // Any clean up needed related to `setUpFixtures()`. parent::tearDownFixtures(); } /** * @afterClass */ public static function tearDownFixturesAfterClass() { // Close database connection and other clean up related to `setUpFixturesBeforeClass()`. parent::tearDownFixturesAfterClass(); } }
TestListener
â ī¸ Important â ī¸
The TestListener polyfill in PHPUnit Polyfills 2.0/3.0 is not (yet) compatible with PHPUnit 10.x/11.x.
If you need the TestListener polyfill, it is recommended to stay on the PHPUnit Polyfills 1.x series for the time being and to watch and upvote the related ticket.
The below documentation is for the PHPUnit 6.x-9.x TestListener polyfill implementation.
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.
Note: while deprecated in PHPUnit 7, the TestListener interface has not yet been removed and is still supported in PHPUnit 9.x.
If your test suite does not need to support PHPUnit < 7, it is strongly recommended to use the TestRunner hook interfaces extensions instead.
However, for test suites that still need to support PHPUnit 6 or lower, implementing the TestListener
interface is the only viable option.
Yoast\PHPUnitPolyfills\TestListeners\TestListenerDefaultImplementation
This TestListenerDefaultImplementation
trait overcomes the signature mismatches by having multiple versions and loading the correct one depending on the PHPUnit version being used.
Similar to the TestCase
implementation, snake_case methods without type declarations are used to get round the signature mismatches. The snake_case methods will automatically be called.
Implementations of the TestListener
interface may be using any of the following patterns:
// PHPUnit 6. class MyTestListener extends \PHPUnit\Framework\BaseTestListener {} // PHPUnit 7+. class MyTestListener implements \PHPUnit\Framework\TestListener { use \PHPUnit\Framework\TestListenerDefaultImplementation; }
Replace these with:
use PHPUnit\Framework\TestListener; use Yoast\PHPUnitPolyfills\TestListeners\TestListenerDefaultImplementation; class MyTestListener implements TestListener { use TestListenerDefaultImplementation; // Implement any of the snakecase methods, for example: public function add_error( $test, $e, $time ) { // Do something when PHPUnit encounters an error. } }
Frequently Asked Questions
Q: Will this package polyfill functionality which was removed from PHPUnit ?
As a rule of thumb, removed functionality will not be polyfilled in this package.
For frequently used, removed PHPUnit functionality, "helpers" may be provided. These helpers are only intended as an interim solution to allow users of this package more time to refactor their tests away from the removed functionality.
Removed functionality without PHPUnit native replacement
Q: Can this library be used when the tests are being run via a PHPUnit Phar file ?
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 do I run my tests when the library is installed via the GitHub Actions setup-php
action ?
As of shivammathur/setup-php version 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.
- name: Setup PHP with tools uses: shivammathur/setup-php@v2 with: php-version: '8.0' tools: phpunit-polyfills
The above step will install both the PHPUnit Polyfills, as well as PHPUnit, as Composer global packages.
After this step has run, you can run PHPUnit, like you would normally, by using phpunit
.
- name: Run tests run: phpunit
đ If you rely on Composer for autoloading your project files, you will still need to run composer dump-autoload --dev
and include the project local vendor/autoload.php
file as/in your test bootstrap.
đ Why this works:
Composer will place all files in the global Composer
bin
directory in the system path and the Composer installed PHPUnit version will load the Composer globalautoload.php
file, which will automatically also load the PHPUnit Polyfills.
Now you may wonder, "what about if I explicitly request both phpunit
as well as phpunit-polyfills
in tools
?"
In that case, when you run phpunit
, the PHPUnit PHAR will not know how to locate the PHPUnit Polyfills, so you will need to do some wizardry in your test bootstrap to get things working.
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:
if ( class_exists( '\Yoast\PHPUnitPolyfills\Autoload' ) === false ) { require_once 'vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php'; } $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; 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; exit(1); }
Q: Why don't the PHPUnit Polyfills 3.x versions support running tests on PHPUnit 10 ?
PHPUnit 11.0 introduced the expectUserDeprecationMessage*()
methods. To polyfill these for PHPUnit 10 would mean that the Polyfills package could no longer be a "drop-in" helper package, but would need to set extra requirements on test suites using the polyfills when used with PHPUnit 10 (like hooking into events or compulsory use of the TestCase
s provided by this package).
As it was deemed desirable enough to polyfill the methods, the releases from the 3.x branch of the PHPUnit Polyfills do not support running tests on PHPUnit 10.
The impact of this compromise is minimal, as, in the most common case of running the tests with Composer installed dependencies, this just and only means that test runs on PHP 8.1 will use PHPUnit 9 instead of PHPUnit 10. There is no other impact.
Keep in mind that functionality added in PHPUnit 10, is still polyfilled and available in PHPUnit Polyfills 3.x.
Contributing
Contributions to this project are welcome. Clone the repo, branch off from the oldest #.x branch the patch applies to, make your changes, commit them and send in a pull request against the correct #.x branch.
If you are unsure whether the changes you are proposing would be welcome, please open an issue first to discuss your proposal.
License
This code is released under the BSD-3-Clause License.