Skip to content

Latest commit

 

History

History
314 lines (220 loc) · 9.24 KB

CONTRIBUTING.md

File metadata and controls

314 lines (220 loc) · 9.24 KB
Raw

Contributing

We would love for you to contribute to this project and help make it even better! As a contributor, here are the guidelines we would like you to follow:

Code of Conduct

Help us keep this project open and inclusive. Please read and follow our Code of Conduct.

Got a Question, Problem or Idea?

Start a new discussion and select the appropriate category for it:

  • General: Anything that is relevant to the project.
  • Ideas: Ideas to change/improve the project or propose new features.
  • Polls: Polls with multi options for the community to vote for and discuss.
  • Q&A: Questions for the community to answer, in a question/answer format.
  • Show and tell: Creations, experiments, or tests relevant to the project.

Add or Improve a Feature?

  • For a Major Feature, first open a new discussion in the Ideas category and outline your proposal so that it can be discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project.

  • Small Features can be crafted and directly submitted as a Pull Request.

Found a Bug?

If you find a bug in the source code, you can help us by submitting an issue to our repository. Even better, you can submit a Pull Request with a fix.

Submitting an Issue

Issues are very valuable for any project.

Great bug reports tend to have:

  • A quick summary and/or background.
  • Steps to reproduce.
  • Be specific.
  • Give sample code if you can.
  • What you expected would happen.
  • What actually happens.
  • Notes; why you think this might be happening, tests that didn't work...

You can file new issues by filling out our new issue form.

Submitting a Pull Request

Pull requests are a great way to put your ideas into this project or simply fix something.

Before you submit your Pull Request (PR) consider the following guidelines:

  1. Search GitHub for an open or closed PR that relates to your submission. You don't want to duplicate effort.

  2. Fork the repository to your own GitHub account.

  3. Clone the repository to your machine.

  4. Go to the cloned repository.

    cd php-url

  5. Create a branch from the main branch with a succinct but descriptive name.

    git checkout -b descriptive-name main

  6. Make your changes in the new git branch, including appropriate test cases.

  7. Follow our Coding Rules.

  8. Run the full repository test suite.

    composer tests

  9. Commit your changes using a descriptive commit message that follows our commit message conventions.

    git commit -a

    The optional commit -a command line option will automatically "add" and "rm" edited files.

  10. Push your branch to GitHub:

    git push origin descriptive-name

  11. In GitHub, send a pull request to php-url:main.

  • If we suggest changes then:

    • Make the required updates.

    • Re-run the test suites to ensure tests are still passing.

    • Rebase your branch and force push to your GitHub repository (this will update your Pull Request):

      git rebase main -i
git push -f

That's it! Thank you for your contribution!

After Your Pull Request is Merged

After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:

  • Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:

    git push origin --delete descriptive-name

  • Check out the main branch:

    git checkout main -f

  • Delete the local branch:

    git branch -D descriptive-name

  • Update your ´main´ branch with the latest upstream version:

    git pull --ff upstream main

Coding Rules

To ensure consistency throughout the source code, keep these rules in mind as you are working:

  • All features or bug fixes must be tested by one or more specs (unit-tests).

    You can use the following command to check the tests:

    composer phpunit

  • All new feature must be documented in the README.md file.

  • We use PHP CodeSniffer and PHP Mess Detector to define our code standards.

    You can use the following commands to check the status of your code:

    composer phpcs
    composer phpmd

    You can use the following command to automatically format errors found with PHP CodeSniffer:

    composer fix

Commit Message Conventions

We have very precise rules over how our Git commit messages must be formatted. This format leads to easier to read commit history.

Each commit message consists of a header, a body, and a footer.

<header>
<BLANK_LINE>
<body>
<BLANK_LINE>
<footer>

The header is mandatory and must conform to the Commit Message Header format.

The body is optional. When the body is present it must be at least 20 characters long and must conform to the Commit Message Body format.

The footer is optional. The Commit Message Footer format describes what the footer is used for and the structure it must have.

Commit Message Header

<type>(<scope>): <short summary>
  │          │          │
  │          │          └─> # Summary in present tense. Not capitalized. No period at the end.
  │          │
  │          └─> # Relevant short word. Not capitalized.
  │
  └─> # Commit Type: build|ci|docs|feat|fix|perf|refactor|test.

The <type> and <summary> fields are mandatory, the (<scope>) field is optional.

Type

Must be one of the following:

  • build: Changes that affect the build system or external dependencies.
  • ci: Changes to our CI configuration files and scripts.
  • docs: Documentation only changes.
  • feat: A new feature.
  • fix: A bug fix.
  • perf: A code change that improves performance.
  • refactor: A code change that neither fixes a bug nor adds a feature.
  • test: Adding missing tests or correcting existing tests.

Scope

A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis. For example:

feat(parser): add ability to parse arrays

Summary

Use the summary field to provide a succinct description of the change:

  • Use the imperative, present tense: "change" not "changed" nor "changes".
  • Don't capitalize the first letter.
  • No dot (.) at the end.

Commit Message Body

Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".

Explain the motivation for the change in the commit message body. This commit message should explain why you are making the change. You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.

Commit Message Footer

The footer can contain information about breaking changes and deprecations and is also the place to reference GitHub issues, Jira tickets, and other PRs that this commit closes or is related to. For example:

BREAKING CHANGE: <breaking change summary>
<BLANK LINE>
<breaking change description + migration instructions>
<BLANK LINE>
<BLANK LINE>
Fixes #<issue number>

or

DEPRECATED: <what is deprecated>
<BLANK LINE>
<deprecation description + recommended update path>
<BLANK LINE>
<BLANK LINE>
Closes #<pr number>

Breaking Change section should start with the phrase "BREAKING CHANGE:" followed by a summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions.

Similarly, a Deprecation section should start with "DEPRECATED:" followed by a short description of what is deprecated, a blank line, and a detailed description of the deprecation that also mentions the recommended update path.

This contribution guide is inspired from the Angular Contribution Guide.