# Contributing to PHPUnit

## Welcome!

We look forward to your contributions! Here are some examples how you can contribute:

* [Report a bug](https://github.com/sebastianbergmann/phpunit/issues/new?labels=type/bug&template=BUG.md)
* [Propose a new feature](https://github.com/sebastianbergmann/phpunit/issues/new?labels=type/enhancement&template=FEATURE_REQUEST.md)
* [Send a pull request](https://github.com/sebastianbergmann/phpunit/pulls)


## We have a Code of Conduct

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


## Use of LLM-based coding assistants

This project does not ban the use of LLM-based coding assistants.

Such a ban would not work. Text and code generated by an LLM-based coding assistant cannot be reliably identified as such, and a rule that cannot be enforced merely punishes the honest. What a ban would actually achieve is that people stop telling us how a contribution came to be, which is the opposite of what we need.

What this project does require is that a human is accountable for every contribution. The problem is not that a machine was involved. The problem is when nobody has understood, verified, and taken responsibility for what was submitted, and the effort saved on the contributor's side is simply shifted onto the maintainers.

The rules below follow from that.


### A human must be accountable for the contribution

You are responsible for everything you submit, no matter which tools you used to produce it. By opening an issue or a pull request, you state that you have read and understood its contents, that you consider it correct, and that you are able to explain and defend it.

If you cannot explain why a change is correct, do not submit it. If you have not run the code you are proposing, do not submit it. If you have not reproduced the bug you are reporting, say so explicitly.

Note that "I have understood and verified this" is a statement about you, not about the tool you used. Do not submit output you do not understand in the hope that a maintainer will figure out whether it is any good. Reviewing a plausible-looking but unverified contribution costs more time than writing the change from scratch, and that time is taken from other contributors.


### Do not let an LLM-based coding assistant act or speak on your behalf

Issues and pull requests must be opened by a human. Do not let an LLM-based coding assistant act or speak on your behalf, neither when opening an issue or a pull request nor when responding to follow-up questions or review feedback. We are not willing to communicate with a chat bot.

Using an LLM-based coding assistant to help you write, translate, or proofread what you want to say is fine. Handing the conversation over to one is not.


### Disclose how you used an LLM-based coding assistant

If you used an LLM-based coding assistant to find, reproduce, or write up an issue, or to generate code for a pull request, please say so and describe how it was used.

Disclosing this does not disqualify a contribution. It changes how we triage and review it, in the same way that knowing whether a bug report comes from a minimized reproducer or from a production stack trace changes how we look at it. Do not hide it: a disclosure that surfaces later, when a contribution turns out to be wrong, costs the trust that this project runs on.


### You remain responsible for the licensing of your contribution

The rules in "Any contributions you make will be under the BSD-3-Clause License" and "Do Not Violate Copyright" below apply to contributions produced with an LLM-based coding assistant just as they do to any other contribution. You are responsible for ensuring that what you submit can be licensed under this project's license.


## Any contributions you make will be under the BSD-3-Clause licence

When you submit code changes, your submissions are understood to be under the same [BSD-3-Clause licence](https://github.com/sebastianbergmann/phpunit/blob/main/LICENSE) that covers the project. By contributing to this project, you agree that your contributions will be licensed under its BSD-3-Clause licence.


### Do not violate copyright

Only submit a pull request with your own original code. Do NOT submit a pull request containing code which you have largely copied from
another project, unless you wrote the respective code yourself.

Open Source does not mean that copyright does not apply. Copyright infringements will not be tolerated and can lead to you being banned from this project and repository.


## Write bug reports with detail, background, and sample code

[This is an example](https://github.com/sebastianbergmann/phpunit/issues/4376) of a bug report Sebastian Bergmann wrote, and he thinks it's not too bad.

In your bug report, please provide the following:

* 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 (possibly including why you think this might be happening, or stuff you tried that didn't work)

Please do not report a bug for a [version of PHPUnit that is no longer supported](https://phpunit.de/supported-versions.html). Please do not report a bug if you are using a [version of PHP that is not supported by the version of PHPUnit](https://phpunit.de/supported-versions.html) you are using.

Please do not report an issue if you are not using PHPUnit directly, but rather a third-party wrapper around it.

Please do not report an issue if you are using a third-party extension such as alternative output printers.

Please post code and output as text ([using proper markup](https://guides.github.com/features/mastering-markdown/)). Do not post screenshots of code or output.

Please include the output of `composer info | sort` if you installed PHPUnit using Composer.

Please use the most specific issue tracker to search for existing tickets and to open new tickets:

* [General problems](https://github.com/sebastianbergmann/phpunit/issues)
* [Code Coverage](https://github.com/sebastianbergmann/php-code-coverage/issues)
* [Documentation](https://github.com/sebastianbergmann/phpunit-documentation-english/issues)
* [Website](https://github.com/sebastianbergmann/phpunit-website/issues)

If an LLM-based coding assistant was involved in finding, reproducing, or writing up the issue, please observe the rules in "Use of LLM-based Coding Assistant" above.


## Workflow for pull requests

1. Fork the repository.
2. Create your branch from `main` 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.
3. Implement your change and add tests for it.
4. Ensure the test suite passes.
5. Ensure the code complies with our coding guidelines (see below).
6. Send that pull request!

Please make sure you have [set up your username and email address](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) for use with Git. Strings such as `silly nick name <root@localhost>` look really stupid in the commit history of a project.

We encourage you to [sign your Git commits with your GPG key](https://docs.github.com/en/github/authenticating-to-github/signing-commits).

Pull requests for bug fixes must be made for the oldest branch that is [supported](https://phpunit.de/supported-versions.html). Pull requests for new features must be based on the `main` branch.

We are trying to keep backwards compatibility breaks in PHPUnit to an absolute minimum. Please take this into account when proposing changes.

If an LLM-based coding assistant was involved in producing the proposed changes, please observe the rules in "Use of LLM-based Coding Assistant" above.

Due to time constraints, we are not always able to respond as quickly as we would like. Please do not take delays personal and feel free to remind us if you feel that we forgot to respond.


## Coding Guidelines

This project comes with a configuration file (located at `/.php-cs-fixer.dist.php` in the repository) and an executable for [php-cs-fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) (located at `/tools/php-cs-fixer` in the repository) that you can use to (re)format your source code for compliance with this project's coding guidelines:

```bash
$ ./tools/php-cs-fixer fix
```

Please understand that we will not accept a pull request when its changes violate this project's coding guidelines.


## Static Analysis

This project comes with a configuration file (located at `/phpstan.neon` in the repository) and an executable for [PHPStan](https://phpstan.org/) (located at `/tools/phpstan` in the repository) that you can use to perform static analysis:

```bash
$ ./tools/phpstan
```


## Using PHPUnit from a Git checkout

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

```bash
$ git clone git://github.com/sebastianbergmann/phpunit.git

$ cd phpunit
```

Install PHPUnit's dependencies using [Composer](https://getcomposer.org/):

```bash
$ ./tools/composer install
```

The `phpunit` script can be used to invoke the PHPUnit test runner:

```bash
$ ./phpunit --version
```


## Running PHPUnit's own test suite

After following the steps shown above, PHPUnit's own test suite is run like this:

```bash
$ ./phpunit
```
