| 1 |
efrain |
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 |
- [Helpful article about forking](https://help.github.com/articles/fork-a-repo/ "Forking a GitHub repository")
|
|
|
19 |
- [Helpful article about 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 |
|