Thank you for taking the time to contribute!
All types of contributions are encouraged and valued. See the Table of Contents for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make things a lot easier for maintainers and improve the experience for everyone.
If you like this project but don't have time to contribute directly there are other easy ways to support it and show your appreciation:
- Star the repository
- Use
bebat/verifyin your own project- Share it on social media
- Mention this library at local meetups and tell your friends/colleagues
This project and everyone participating in it is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].
If you have any questions about BeBat/Verify the first, best place to check is the project documentation. If your question is not addressed by the existing documentation it may be useful to search for any existing issues related to your question. If you find a suitable issue but still need clarification, you may write your question as a comment to that issue.
If you feel your question is still not properly address, please do the following:
- Open a new issue.
- Provide as much context as you can about what you're experiencing.
- Be sure to include relevant environment details, such as PHP and BeBat/Verify versions.
There are several steps you can do before reporting a bug that will make fixing the issue quicker and easier for maintainers, or could lead to your issue being resolved without creating a bug report at all.
- Make sure that you are using the latest versions of BeBat/Verify and all of its dependencies.
- Check the documentation to see if your issue is addressed there.
- Search existing issues for your problem. If an issue already exists feel free to give it a
+1and/or add additional context. - Collect any relevant information about your issue:
- OS version & platform (Windows, Linux, macOS, x86, ARM, etc)
- Web server & PHP version (nginx, Apache, etc)
- Any relevant input & output
- Especially any exception output & stacktraces
- Can you consistently reproduce the issue?
- Has the behavior changed between versions?
You must never report security related issues, vulnerabilities, or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead, sensitive bugs must be sent via email to [email protected]. See the Security Policy for more details.
We use GitHub issues to track bugs and errors. If you run into an issue with the project:
- Open a Bug Report Issue
- Fill out all the relevant fields in the form
- Please provide as much context as possible, this usually includes your code. Ideally you should isolate the problem and create a simplified test case.
Once your issue is filed the maintainers will do our best to reproduce the problem, determine the appropriate course of action, and resolve the issue in a timely manner.
If you have an idea on how to improve BeBat/Verify we are eager to hear it! We welcome any constructive suggestions for improvements to the project and look forward to hearing them.
- Make sure that you are using the latest versions of BeBat/Verify and all its dependencies.
- Check the project documentation to see if your idea has already been implemented.
- Search the existing issues to see if the enhancement has already been suggested. If an issue already exists feel free to give it a
+1and/or add additional context. - Find out whether your idea fits with the scope and aims of the project. Ideally new features should be useful to a broad set of users and/or streamline something that would otherwise be highly complex. We cannot add features just for their own sake.
- Open a Feature Request
- Fill out the relevant fields on the form
- In the description be sure to include why this feature is important, what use cases will it have, how will it improve people's experiences using the library, etc.
- Include as many examples as you think are relevant. Be sure to consider edge cases and error conditions as well.
- Try to estimate whether this feature will require a major or minor version change to the library. In general, if a feature breaks or replaces some already existing functionality it will require a major change, otherwise it will be added to a minor (or possibly patch) release.
When contributing to this project, you affirm that you have authored 100% of the content, that you have the necessary rights to the content, and that the content you contribute may be provided under the project's license.
We are thrilled you would like to contribute code to BeBat/Verify! This is truly one of the best ways to help support our project and the open source community as a whole. Before writing code for the library, we ask that you consider a few things.
- Is this feature or bug fix needed? Opening a pull request to https://github.com/bbatsche/Verify is no guarantee that it will be accepted and merged. If you are not certain whether your contribution will be useful open a bug report or feature request first to discuss it with maintainers.
- Will this change affect or break existing functionality? If there is some functionality being removed it will first need to be deprecated in the next minor release and only then can the new functionality be added, targeting the next major version.
- Will this break compatibility with previous versions of PHP? BeBat/Verify has a long tail of support which is a double edged sword. If your feature is worthwhile it may be added in to the next major release when the minimum version of PHP can be updated.
There is minimal tooling required to contribute to BeBat/Verify. In general the software required to write code for this library is the same as it is to use it, ie:
- PHP 7.2 or greater
- Git
- Composer
- A coverage driver such as Xdebug or PCOV
- A text editor and terminal of your choice.
To get started, follow the steps below:
- Fork https://github.com/bbatsche/Verify to your own profile
- Clone your fork locally
- Create a new branch for your work
- If you are working on a previous version of the library be sure to branch off of the correct version branch.
- Run
composer install - Begin your work!
In order to ensure code quality and consistency, BeBat/Verify has various style checks and unit tests bundled with it. These are defined in composer scripts. The included commands are:
style:check— Check that PHP files follow coding standardsstyle:fix— Automatically fix any coding standard errorstest:static— Run static analysis on codetest:phpunit— Run PHPUnit tests on codetest:coverage— Run PHPUnit tests and generate a coverage reporttest— Runstyle:check,test:static, andtest:phpunitin sequence
BeBat/Verify uses CaptainHook to manage git hooks during development. Whenever you create a commit, CaptainHook will automatically lint your code and run through composer test for you. In addition, before pushing your code Captainhook will check the test coverage to ensure it is over 80%. Do not skip or disable the git hooks unless you have a very good reason for doing so!
Finally, there are two additional tools meant to keep dependencies well defined:
vendor/bin/composer-require-checker— Check that all dependencies are explicitly defined incomposer.jsoncomposer normalize— Make surecomposer.jsonis in a consistent order and format
If you modify composer.json make sure to run composer normalize before pushing your code to GitHub. Both these tools will be run against every pull request before merging.
The final step for whatever coding work you perform is, naturally, opening a pull request. The pull request template will guide you through the required steps and details to get your PR merged easily. Make sure to read the instructions, fill out the required sections, and mark the appropriate items on the checklist. Failure to do so could cause delays in getting your pull request reviewed and merged.
This guide is based in part on content from contributing-gen.