Skip to content

Latest commit

 

History

History
90 lines (55 loc) · 3.51 KB

CONTRIBUTING.md

File metadata and controls

90 lines (55 loc) · 3.51 KB
Raw

Contributing to the PHP Standard Library

Thank you for contributing to the PHP Standard Library!

Code of Conduct

The code of conduct is described in CODE_OF_CONDUCT.md

Issues

We use GitHub issues to track issues within PSL.

Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.

Getting started

Contributing to open-source can be scary. Don't be afraid! We are looking forward working together to improve this package!

Here is a small checklist to get you going:

  • Discuss the changes you want to make first!
  • Create a fork of this repository.
  • Clone your own repository.
  • Run make install to get everything set-up for you.
  • Checkout a new branch and make the changes you want to make.
  • Run make check to verify your code is ok to submit.
  • Submit your Pull Request.

Submitting Pull Requests

Before we can merge your Pull-Request, here are some guidelines that you need to follow.

These guidelines exist not to annoy you, but to keep the code base clean, unified and future proof.

Principles

  • All functions should be typed as strictly as possible
  • The library should be internally consistent
  • References may not be used
  • Arguments should be as general as possible. For example, for array functions, prefer iterable inputs where practical, falling back to array when needed.
  • Return types should be as specific as possible
  • All files should contain declare(strict_types=1);

Consistency Rules

This is not exhaustive list.

  • Functions argument order should be consistent within the library
    • All iterable-related functions take the iterable as the first argument ( e.g. Dict\map and Dict\filter )
    • $haystack, $needle, and $pattern are in the same order for all functions that take them
  • Functions should be consistently named.
  • If an operation can conceivably operate on either keys or values, the default is to operate on the values - the version that operates on keys should have _key suffix (e.g. Iter\last, Iter\last_key, Iter\contains, Iter\contains_key )
  • Iterable functions that do an operation based on a user-supplied keying function for each element should be suffixed with _by (e.g. Vec\sort_by, Dict\group_by, Math\max_by)

Tests

PSL tries to maintain a 100% code coverage, meaning everything within the library MUST be tested.

If you are submitting a bug-fix, please add a test case to reproduce the bug. If you are submitting a new feature, please make sure to add tests for all possible code paths.

To run the tests, use make unit-tests.

Code Style

PSL follows a custom set of rules that extend PSR-12, PSR-2, and PSR-1.

To check if your code contains any issues that violate PSL rules, use make coding-standard-check.

You may fix many of the issues using make coding-standard-fix.

Static Analysis

PSL uses Psalm static analysis tool to avoid type issues within the code base, and to provide a better API for the end user.

PSL is configured to pass the strictest psalm level.

To ensure that your code doesn't contain any type issues, use make static-analysis.

To ensure that your code doesn't introduce any security issues, use make security-analysis

License

By contributing to the PHP Standard Library ( PSL ), you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.

Security Disclosures

You can read more about how to report security issues in our Security Policy.