Skip to content

Latest commit

 

History

History
151 lines (109 loc) · 5.2 KB

CONTRIBUTING.md

File metadata and controls

151 lines (109 loc) · 5.2 KB
Raw

Contributing

Thank you for considering a contribution to our project! We welcome all fixes and improvements!

Alright, to get going:

  1. Fork this repository.
  2. Create your feature branch (git checkout -b my-new-feature).
  3. Commit your changes (see Conventional Commits below).
  4. Push to the branch (git push origin my-new-feature).
  5. Create new Pull Request.

Targeting earlier versions

Feature branches made off of master target PHP 8. To target earlier releases and versions of PHP, checkout the main branch for that series:

# to target changes for the next release in the 1.x (PHP 5) series:
$ git checkout -b next/1.x/describe-the-fix next/1.x/main

# to target changes for the next release in the 2.x (PHP 7) series:
$ git checkout -b next/2.x/describe-the-fix next/2.x/main

# to target changes for the next release in the 3.x (PHP 8) series:
$ git checkout -b whiz-bang master

Note that, technically, you don't have to name your feature branch with the "next/1.x/" or "next/2.x/" prefix. However, it's helpful for us when evaluating pull requests, because the intention is clear.

Fix and Feature Propagation

Bug fixes should go into the lowest affected version, and then be patched into successively higher versions. For example, if a bug is found in version 1.9.0; and it's found to exist in version 2.2.10, but not master; then it should be patched in next/1.x/main and next/2.x/main but not master. Likewise, if a bug is found in 2.2.10; but not 1.9.0 or master; then it should go into next/2.x/main only.

Similarly, features propagate forward using the same process: patch them in the lowest version accepting features (currently next/2.x/main) and patch them forward (currently to master).

Conventional Commits

This repository follows the Conventional Commits guidelines. Go read that then, when making commits, ensure that your commit messages conform.

Example conforming commit message:

feat: add more foo to the bar

Fixes #123

BREAKING CHANGE: more foo in bar breaks baz

Optionally, you can use commitizen to format your commit messages.

$ npm install -g commitizen
$ npm install -g cz-conventional-changelog
$ echo '{ "path": "cz-conventional-changelog" }' >> ~/.czrc

And then commit using git cz. You'll be prompted to describe your commit.

Possible Types and Scopes

Type must be one of the following:

Type Description
ci Changes to CI configuration files and scripts.
docs Documentation only changes.
feat A change that adds functionality not present before.
fix Repair to code or documentation so the two agree.
perf Changes that improve performance of code or build.
refac A change that neither adds a feature nor fixes a bug.
style Changes not affecting code meaning.
test Adding missing tests, or correcting existing tests.

Scopes generally reflect the top-level directories under src/, and could be any of these:

  • config
  • builder
  • handler
  • payload
  • response
  • scrubber
  • sender
  • truncation
  • util

If a change affects multiple classes under src/, then choose a scope that's most affected or relevant to the change at hand.

Guidelines for Writing Commit Messages

Use the imperative voice, like "add" instead of "adds" or "added". In the subject line, use lowercase with no ending period and stick to fewer than 50 characters. In the body, include the motivation for the change and contrast it with the prior behavior.

Indicate "BREAKING CHANGE" in the footer when that's the case. If you're unsure if a change is breaking, assume it is and seek clarification via our Discussion Q&A.

Testing

New code should receive test coverage: add them in tests/.

To run the tests: composer test

To fix code style issues: composer fix

Contribution Checklist

We appreciate all effort to improve the library! To ensure your contribution gets pulled in without delay, please:

  1. Discuss the change before implementing. It's easiest to change code before it's written, and the best code comes from collaborative ideation.
  2. Target the change to the correct branches. Remember: start at the lowest affected branches and patch upwards. This means a bug fix may need three branch patches and a feature may need two.
  3. Follow the coding conventions. That means code style, good variable names, compact functions, etc. New things should look like old things, whenever possible.
  4. Include tests and fix failures. No tests, no merge. If the CI automation fails, fix that as well. A common mistake is to make a change that works for a new version of PHP, but not the older ones we must support: automation catches this.
  5. Follow the code of conduct. Do all of the above with grace and courtesy, please. We're all volunteers here.

Need help?

Ask in our Discussion Q&A