src
4 months ago
.readthedocs.yaml
1 year ago
CHANGELOG.md
4 months ago
CONTRIBUTING.md
1 year ago
LICENSE
1 year ago
README.md
4 months ago
composer.json
4 months ago
CONTRIBUTING.md
46 lines
| 1 | # Want to contribute? |
| 2 | |
| 3 | If you would like to contribute, here are some notes and guidelines: |
| 4 | |
| 5 | - 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 |
| 6 | - 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 |
| 7 | - The code must work with all PHP versions that we support (currently PHP 7.4 to PHP 8.2). |
| 8 | - You can call `composer versions` to test version compatibility. |
| 9 | - Code style should be maintained. |
| 10 | - `composer style` will identify any issues with Coding Style`. |
| 11 | - `composer fix` will fix most issues with Coding Style. |
| 12 | - All code changes must be validated by `composer check`. |
| 13 | - Please include Unit Tests to verify that a bug exists, and that this PR fixes it. |
| 14 | - Please include Unit Tests to show that a new Feature works as expected. |
| 15 | - Please don't "bundle" several changes into a single PR; submit a PR for each discrete change/fix. |
| 16 | - Remember to update documentation if necessary. |
| 17 | |
| 18 | - [](https://help.github.com/articles/fork-a-repo/ "Forking a GitHub repository"Helpful article about forking](https://help.github.com/articles/fork-a-repo/ "Forking a GitHub repository"](https://help.github.com/articles/fork-a-repo/ "Forking a GitHub repository") |
| 19 | - [](https://help.github.com/articles/using-pull-requests/ "Pull Requests"Helpful article about pull requests](https://help.github.com/articles/using-pull-requests/ "Pull Requests"](https://help.github.com/articles/using-pull-requests/ "Pull Requests") |
| 20 | |
| 21 | ## Unit Tests |
| 22 | |
| 23 | When writing Unit Tests, please |
| 24 | - Always try to write Unit Tests for both the happy and unhappy paths. |
| 25 | - Put all assertions in the Test itself, not in an abstract class that the Test extends (even if this means code duplication between tests). |
| 26 | - Include any necessary `setup()` and `tearDown()` in the Test itself. |
| 27 | - 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()`. |
| 28 | - Use the `ExcelError` functions in assertions for Excel Error values in Excel Function implementations. |
| 29 | <br />Not only does it reduce the risk of typos; but at some point in the future, ExcelError values will be an object rather than a string, and we won't then need to update all the tests. |
| 30 | - Don't over-complicate test code by testing happy and unhappy paths in the same test. |
| 31 | |
| 32 | 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 unchanged classes to see what the test is doing. |
| 33 | |
| 34 | ## How to release |
| 35 | |
| 36 | 1. Complete CHANGELOG.md and commit |
| 37 | 2. Create an annotated tag |
| 38 | 1. `git tag -a 1.2.3` |
| 39 | 2. Tag subject must be the version number, eg: `1.2.3` |
| 40 | 3. Tag body must be a copy-paste of the changelog entries. |
| 41 | 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. |
| 42 | 4. Github seems to remove markdown headings in the Release Notes, so you should edit to restore these. |
| 43 | |
| 44 | > **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.) |
| 45 | |
| 46 |