diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f59535331c..957dc48116 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,19 +2,40 @@ If you would like to contribute, here are some notes and guidelines: - - All new development happens on feature/fix branches, and are then merged to the `master` branch once stable; so the `master` branch is always the most up-to-date, working code - - Tagged releases are made from the `master` branch - - If you are going to be submitting a pull request, please fork from `master`, and submit your pull request back as a fix/feature branch referencing the GitHub issue number - - Code style might be automatically fixed by `composer fix` - - All code changes must be validated by `composer check` + - All new development should be on feature/fix branches, which are then merged to the `master` branch once stable and approved; so the `master` branch is always the most up-to-date, working code + - If you are going to submit a pull request, please fork from `master`, and submit your pull request back as a fix/feature branch referencing the GitHub issue number + - The code must work with all PHP versions that we support (currently PHP 7.4 to PHP 8.2). + - You can call `composer versions` to test version compatibility. + - Code style should be maintained. + - `composer style` will identify any issues with Coding Style`. + - `composer fix` will fix most issues with Coding Style. + - All code changes must be validated by `composer check`. + - Please include Unit Tests to verify that a bug exists, and that this PR fixes it. + - Please include Unit Tests to show that a new Feature works as expected. + - Please don't "bundle" several changes into a single PR; submit a PR for each discrete change/fix. + - [Helpful article about forking](https://help.github.com/articles/fork-a-repo/ "Forking a GitHub repository") - [Helpful article about pull requests](https://help.github.com/articles/using-pull-requests/ "Pull Requests") +## Unit Tests + +When writing Unit Tests, please + - Always try to write Unit Tests for both the happy and unhappy paths. + - Put all assertions in the Test itself, not in an abstract class that the Test extends (even if this means code duplication between tests). + - Include any necessary `setup()` and `tearDown()` in the Test itself. + - If you change any global settings (such as system locale, or Compatibility Mode for Excel Function tests), make sure that you reset to the default in the `tearDown()`. + +This makes it easier to see exactly what is being tested when reviewing the PR. I want to be able to see it in the PR, not have to hunt in other classes to see what the test is doing. + ## How to release 1. Complete CHANGELOG.md and commit 2. Create an annotated tag 1. `git tag -a 1.2.3` 2. Tag subject must be the version number, eg: `1.2.3` - 3. Tag body must be a copy-paste of the changelog entries -3. Push tag with `git push --tags`, GitHub Actions will create a GitHub release automatically + 3. Tag body must be a copy-paste of the changelog entries. +3. Push the tag with `git push --tags`, GitHub Actions will create a GitHub release automatically, and the release details will automatically be sent to packagist. +4. Github seems to remove markdown headings in the Release Notes, so you should edit to restore these. + +> **Note:** Tagged releases are made from the `master` branch. Only in an emergency should a tagged release be made from the `release` branch. (i.e. cherry-picked hot-fixes.) + diff --git a/composer.json b/composer.json index 1e8e5f6c07..de3afb1e55 100644 --- a/composer.json +++ b/composer.json @@ -42,13 +42,19 @@ ], "scripts": { "check": [ + "phpcs src/ tests/ --report=checkstyle", + "phpcs --report-width=200 samples/ src/ tests/ --ignore=samples/Header.php --standard=PHPCompatibility --runtime-set testVersion 7.4- -n", "php-cs-fixer fix --ansi --dry-run --diff", - "phpcs", "phpunit --color=always", - "phpstan analyse --ansi" + "phpstan analyse --ansi --memory-limit=2048M" + ], + "style": [ + "phpcs src/ tests/ --report=checkstyle", + "php-cs-fixer fix --ansi --dry-run --diff" ], "fix": [ - "php-cs-fixer fix --ansi" + "phpcbf src/ tests/ --report=checkstyle", + "php-cs-fixer fix" ], "versions": [ "phpcs --report-width=200 samples/ src/ tests/ --ignore=samples/Header.php --standard=PHPCompatibility --runtime-set testVersion 7.4- -n"