Contributing to Clock

Important Note

The contributing guidelines for this project are heavily inspired by, and borrowed from, the contributing guidelines of PHPUnit.

Welcome!

This project accepts contributions of code and documentation from the community. These contributions can be made in the form of Issues or Pull Requests on the Clock repository.

Here are some examples how you can contribute:

• Report a bug
• Propose a new feature
• Send a pull request

I look forward to your contributions!

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Any contributions you make will be under the MIT License

When you submit code changes, your submissions are understood to be under the same MIT License that covers the project. By contributing to this project, you agree that your contributions will be licensed under its MIT License.

Workflow for Pull Requests

• Fork the repository.
• Create your branch from `master` if you plan to implement new functionality or change existing code significantly. - Create your branch from the oldest branch that is affected by the bug if you plan to fix a bug. - Pull requests for bug fixes must be made for the oldest branch that is supported.
• Implement your change and add tests for it.
• Ensure the test suite passes.
• Ensure the code complies with our coding guidelines (see below).
• Create the pull request.

Please make sure you have set up your username and email address for use with Git. You are encouraged to sign your Git commits with your GPG key.

Backwards compatibility breaks in this project are being kept to an absolute minimum. Please take this into account when proposing changes.

Guidelines

Before we look into how, here are the guidelines. If your Pull Requests fail to pass these guidelines it will be declined, and you will need to re-submit when you?ve made the changes. This might sound a bit tough, but it is required for me to maintain quality of the code-base.

Git Checkout

The following commands can be used to perform the initial checkout of Clock:

$ git clone https://github.com/ericsizemore/clock.git
$ cd clock

Install Clock's dependencies using Composer:

$ composer install

PHP Style and Coding Guidelines

Please ensure all new contributions match the PSR-12 coding style guide.

This project attempts to adhere to PHPStan level 9 with strict rules and bleeding edge. Please ensure any contributions do as well.

This project comes with configuration files for various tools that are used within the development workflow of this project. Please understand that I will not accept a pull request when its changes violate this project's coding guidelines.

Coverage Check

No configuration is needed for PHPUnit Coverage Check. You can use PHPUnit Coverage Check to check the coverage percentage in the codebase after your changes. I try to stick to 100% line coverage.

$ composer run-script coverage

Infection (mutation testing)

The configuration file can be found at infection.json5, in the repository, for Infection. You can use Infection to perform mutation testing:

$ composer run-script analyze:mutation

PHPStan

The configuration file can be found at phpstan.neon, in the repository, for PHPStan. You can use PHPStan to perform static analysis:

$ composer run-script analyze:static

Psalm

The configuration file can be found at psalm.xml, in the repository, for Psalm. You can use Psalm to perform static analysis (with a focus on type checking):

$ composer run-script analyze:psalm

PHP-CS-Fixer

The configuration file can be found at .php-cs-fixer.dist.php, in the repository, for PHP-CS-Fixer. You can use PHP-CS-Fixer to (re)format your source code for compliance with this project's coding guidelines:

$ composer run-script cs:fix

Unit tests (via PHPUnit)

The configuration file can be found at phpunit.xml, in the repository, for PHPUnit. You can run the test suite with:

$ composer run-script test

Documentation

If you change anything that requires a change to documentation then you will need to add it. New methods, parameters, changing default values, adding constants, etc. are all things that will require a change to documentation. The change-log must also be updated for every change. Also, PHPDoc blocks must be maintained.

Documenting functions/variables (PHPDoc)

Please ensure all new contributions adhere to:

• PSR-5 PHPDoc
• PSR-19 PHPDoc Tags

when documenting new functions, or changing existing documentation.

Changelog Entries

If adding new changelog entries, please ensure they adhere to the Keep a Changelog format as much as possible.