Skip to content

Latest commit

 

History

History
93 lines (62 loc) · 5.64 KB

CONTRIBUTING.md

File metadata and controls

93 lines (62 loc) · 5.64 KB
Raw

Contribution Guide

Getting Involved

To encourage active collaboration, Auth0 strongly encourages pull requests, not just bug reports. Pull requests will only be reviewed when marked as "ready for review" (not in the "draft" state) and all tests for new features are passing. Lingering, non-active pull requests left in the "draft" state will eventually be closed.

If you file a bug report, your issue should contain a title and a clear description of the issue. You should also include as much relevant information as possible and a code sample that demonstrates the issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix.

Remember, bug reports are created in the hope that others with the same problem will be able to collaborate with you on solving it. Do not expect that the bug report will automatically see any activity or that others will jump to fix it. Creating a bug report serves to help you and others start on the path of fixing the problem. If you want to chip in, you can help out by fixing any bugs listed in our issue trackers.

Support Questions

Auth0's GitHub issue trackers are not intended to provide integration support. Instead, please refer your questions to the Auth0 Community.

Code Contributions

You may propose new features or improvements to existing SDK behavior by creating a feature request within the repository's issue tracker. If you are willing to implement at least some of the code that would be needed to complete the feature, please fork the repository and submit a pull request.

All development should be done in individual forks using dedicated branches, and submitted against the main default branch.

Pull request titles must follow Conventional Commits rules so our changelogs can be automatically generated. Commits messages are irrelevant as they will be squashed into the Pull request's title during a merge.

The following types are allowed:

  • feat: A new feature
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • style: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc)
  • fix: A bug fix
  • security: A change that improves security
  • docs: Documentation only changes
  • test: Adding missing tests or correcting existing tests

Security Vulnerabilities

If you discover a security vulnerability within this SDK, please review Auth0's Responsible Disclosure Program details the procedure for disclosing security issues. All security vulnerabilities will be promptly addressed.

Unit Testing and 100% Minimum Coverage

We use PEST for testing. You can run composer pest to run the test suite. You can also run composer pest:coverage to generate a code coverage report.

We require 100% code coverage for all new features. If you are adding a new feature, please add tests to cover all of the new code. If you are fixing a bug, please add a test that reproduces the bug and then shows that it has been fixed.

Pull requests that do not meet the minimum coverage requirements will not be merged.

Static Analysis

We use PHPStan and Psalm for static analysis. You can use composer phpstan and composer psalm to run them.

Coding Style

We use PHP CS Fixer to ensure that code styling is consistent. You can run composer phpcs to check for any code style issues. composer phpcs:fix will attempt to automatically fix the issues, but be cautious as it may not always get it right.

We also use Rector to catch edge cases where more optimal refactoring can be made. You can run composer rector to check for any recommendations, and composer rector:fix to accept the suggestions.

It's important to note that our GitHub CI will also run these checks for pull requests, but you should run these locally first to avoid any surprises when you push your code. If you disagree with one of these recommendations, please bring it up in the pull request so we can discuss it. We may decide to adjust the styling rules if we feel it's warranted, but we prefer to avoid it if possible.

PHPDoc

All public methods and classes should be documented with PHPDoc blocks.

Below is an example of a valid documentation block. Note that the @param attribute is followed by two spaces, the argument type, two more spaces, and finally the variable name:

/**
 * Register a binding with the container.
 *
 * @param  string|array  $abstract
 * @param  \Closure|string|null  $concrete
 * @param  bool  $shared
 * @return void
 *
 * @throws \Exception
 */
public function bind($abstract, $concrete = null, $shared = false)
{
    //
}

Code of Conduct

Before making any contributions to this repo, please review Auth0's Code of Conduct. By contributing, you agree to uphold this code.