First of all, thank you for contributing, you're awesome!
To have your code integrated in the API Platform project, there are some rules to follow, but don't panic, it's easy!
If you happen to find a bug, we kindly request you to report it. However, before submitting it, please:
- Check the project documentation available online
Then, if it appears that it's a real bug, you may report it using GitHub by following these 3 points:
- Check if the bug is not already reported!
- A clear title to resume the issue
- A description of the workflow needed to reproduce the bug
NOTE: Don't hesitate giving as much information as you can (OS, PHP version extensions...)
First of all, you must decide on what branch your changes will be based depending of the nature of the change. See the dedicated documentation entry.
To prepare your patch directly in the vendor/
of an existing project (convenient to fix a bug):
- Remove the existing copy of the library:
rm -Rf vendor/api-platform/core
- Reinstall the lib while keeping Git metadata:
composer install --prefer-source
- You can now work directly in
vendor/api-platform/core
, create a new branch:git checkout -b my_patch
- When your patch is ready, fork the project and add your Git remote:
git remote add <your-name> [email protected]:<your-name>/core.git
- You can now push your code and open your Pull Request:
git push <your-name> my_patch
Alternatively, you can also work with the test application we provide:
cd tests/Fixtures/app
./console assets:install --symlink
symfony serve
# if you prefer keeping the server in your terminal:
symfony server:start --dir tests/Fixtures/app
# or if you prefer using the PHP built-in web server
php -S localhost:8000 -t public/
You also have access to a console
:
APP_DEBUG=1 tests/Fixtures/app/console debug:config
The API Platform project follows Symfony coding standards. But don't worry, you can fix CS issues automatically using the PHP CS Fixer tool:
php-cs-fixer.phar fix
And then, add the fixed file to your commit before pushing. Be sure to add only your modified files. If any other file is fixed by cs tools, just revert it before committing.
API Platform is following the Symfony Backward Compatibility Promise.
As users need to use named arguments when using our attributes, they don't follow the backward compatibility rules applied to the constructor.
When you are making a change, make sure no BC break is added.
Adding a deprecation is sometimes necessary in order to follow the backward compatibility promise and to improve an existing implementation.
They can only be introduced in minor or major versions (main
branch) and exceptionally in patch versions if they are critical.
See also the related documentation for Symfony.
When you send a PR, just make sure that:
- You add valid test cases (Behat and PHPUnit).
- Tests are green.
- You make a PR on the related documentation in the api-platform/docs repository.
- You make the PR on the same branch you based your changes on. If you see commits that you did not make in your PR, you're doing it wrong.
- Also don't forget to add a comment when you update a PR with a ping to the maintainers, so he/she will get a notification.
The commit messages must follow the Conventional Commits specification. The following types are allowed:
fix
: bug fixfeat
: new featuredocs
: change in the documentationspec
: spec changetest
: test-related changeperf
: performance optimizationci
: CI-related changechore
: updating dependencies and related changes
Examples:
fix(metadata): resource identifiers from properties
feat(validation): introduce a number constraint
feat(metadata)!: new resource metadata system, BC break
docs(doctrine): search filter on uuids
test(doctrine): mongodb disambiguation
We strongly recommend the use of a scope on API Platform core. Only the first commit on a Pull Request need to use a conventional commit, other commits will be squashed.
On api-platform/core
there are two kinds of tests: unit (phpunit
) and integration tests (behat
).
Note that we stopped using prophesize
for new tests since 3.2, use phpunit
stub system.
Both phpunit
and behat
are development dependencies and should be available in the vendor
directory.
Recommendations:
- don't change existing tests if possible
- always add a new
ApiResource
or a newEntity/Document
to add a new test instead of changing an existing class - as of API Platform 3 each component has its own test directory, avoid the
tests/
directory except for functional tests - dependencies between components must be kept at its minimal (
api-platform/metadata
,api-platform/state
) except for bridges (Doctrine, Symfony, Laravel etc.) - for functional testing with phpunit (see
tests/Functional
, add your ApiResource toApiPlatform\Tests\Fixtures\PhpUnitResourceNameCollectionFactory
)
Note that in most of the testing, you don't need Doctrine take a look at how we write fixtures at:
To launch unit tests:
vendor/bin/phpunit --stop-on-defect
If you want coverage, you will need the pcov
PHP extension and run:
vendor/bin/phpunit --coverage-html coverage --stop-on-defect
Sometimes there might be an error with too many open files when generating coverage. To fix this, you can increase the ulimit
, for example:
ulimit -n 4000
Coverage will be available in coverage/index.html
.
The command to launch Behat tests is:
php -d memory_limit=-1 ./vendor/bin/behat --profile=default --stop-on-failure --format=progress
If you want to launch Behat tests for MongoDB, the command is:
MONGODB_URL=mongodb://localhost:27017 APP_ENV=mongodb php -d memory_limit=-1 ./vendor/bin/behat --profile=mongodb --stop-on-failure --format=progress
To get more details about an error, replace --format=progress
by -vvv
. You may run a mongo instance using docker:
docker run -p 27017:27017 mongo:latest
Start by adding a fixture, usually using Doctrine entities in tests/Fixtures/TestBundle/Entity
. Note that we often duplicate the fixture
in the tests/Fixtures/TestBundle/Document
directory for MongoDB ODM, if your test doesn't need to be tested with MongoDB use the @!mongodb
group on the Behat scenario.
If you need a Given
step, add it to the doctrine context in tests/Core/Behat/DoctrineContext.php
, for example:
/**
* @Given there is a payment
*/
public function thereIsAPayment()
{
$this->manager->persist(new Payment('123.45'));
$this->manager->flush();
}
The last step is to add you feature inside features/
. You can add your test in one of our existing features, or create your own.
API Platform is split into several components. There are tests for each of these, to run them cd src/Doctrine/Common
then composer update
and ./vendor/bin/phpunit
.
We do not provide a way to run all these tests at once yet.
When you open a Pull Request to the API Platform project, you agree to license your code under the MIT license and to transfer the copyright on the submitted code to Kévin Dunglas.
Be sure to you have the right to do that (if you are a professional, ask your company)!
If you include code from another project, please mention it in the Pull Request description and credit the original author.
This section is for maintainers.
- Update the JavaScript dependencies by running
./update-js.sh
(always check if it works in a browser) - Update the
CHANGELOG.md
file (be sure to include Pull Request numbers when appropriate) - Create a signed tag:
git tag -s vX.Y.Z -m "Version X.Y.Z"
- Create a release using GitHub's UI and copy the changelog
- Create a new release of
api-platform/api-platform