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
# or if you prefer using the PHP built-in web server
php -S localhost:8000 -t public/
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.
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.
On api-platform/core
there are two kinds of tests: unit (phpunit
through simple-phpunit
) and integration tests (behat
).
Both simple-phpunit
and behat
are development dependencies and should be available in the vendor
directory.
To launch unit tests:
vendor/bin/simple-phpunit --stop-on-failure -vvv
If you want coverage, you will need the pcov
PHP extension and run:
vendor/bin/simple-phpunit --coverage-html coverage -vvv --stop-on-failure
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.
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