From b2fb18d7e638c21b5d9459d8168b9c5ef34efac1 Mon Sep 17 00:00:00 2001 From: Dominic Luidold Date: Sun, 7 Apr 2024 22:35:03 +0200 Subject: [PATCH 1/2] Revise contributing guide to incorporate recent developments --- CONTRIBUTING.md | 58 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1bef8c85d..1556de2d9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,28 +1,50 @@ -Contributing -============ +# Contributing -First of all, **thank you** for contributing, **you are awesome**! +First of all, **thank you** for contributing, **you are awesome**! With your contribution, you not only improve this +bundle, but also become part of a [great community](https://github.com/nelmio/NelmioApiDocBundle/graphs/contributors) +maintaining it. -Here are a few rules to follow in order to ease code reviews, and discussions before -maintainers accept and merge your work. +## Guidelines -You MUST follow the [PSR-1](http://www.php-fig.org/psr/psr-1/) and -[PSR-2](http://www.php-fig.org/psr/psr-2/). If you don't know about any of them, you -should really read the recommendations. Can't wait? Use the [PHP-CS-Fixer -tool](http://cs.sensiolabs.org/). +Here are a few guidelines to follow in order to ease code reviews, and discussions before maintainers can accept and +merge your work. Thank you! -You MUST run the test suite (run `composer update`, and then execute `composer run phpunit`). +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", +"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in +[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). -You MUST write (or update) unit tests. +### Code Style + +Code MUST adhere to all rules outlined in the +[Symfony Coding Standards](https://symfony.com/doc/current/contributing/code/standards.html) as +defined by the [@Symfony](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/ruleSets/Symfony.rst) rule set, +utilized by the [PHP-CS-Fixer](https://cs.symfony.com) tool. + +You SHOULD run `composer run phpcs-check` to check for any violations. You SHOULD run `composer run phpcs-fix` to +fix any potential issues. + +### Code Quality + +You MUST use the static analysis tool [PHPStan](https://phpstan.org/) to analyse any newly added or revised code within +this bundle. + +You MUST run `composer run phpstan` to check for any violations. You MUST fix all violations related to any newly added +or revised code. + +### Tests + +You MUST write (or update) unit and/or functional tests for any newly added or revised functionality within this bundle. + +You MUST validate newly added or revised tests by running `composer run phpunit`. + +### Documentation You SHOULD write documentation. -Please, write [commit messages that make -sense](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), -and [rebase your branch](http://git-scm.com/book/en/Git-Branching-Rebasing) -before submitting your Pull Request. +You MUST write +[commit messages that make sense](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). -Also, while creating your Pull Request on GitHub, you MUST write a description -which gives the context and/or explains why you are creating it. +You MUST [rebase your branch](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) before submitting your Pull Request. -Thank you! +While creating your Pull Request on GitHub, you MUST write a description which gives the context and/or explains why you +are creating it. From 1e93d4f12eef0f32a0f0adf0cafa0e27a7afca3d Mon Sep 17 00:00:00 2001 From: Dominic Luidold Date: Mon, 8 Apr 2024 22:16:48 +0200 Subject: [PATCH 2/2] Implement PR review feedback Co-authored-by: Djordy Koert --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1556de2d9..3757e042e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,9 +39,9 @@ You MUST validate newly added or revised tests by running `composer run phpunit` ### Documentation -You SHOULD write documentation. +You SHOULD write (or update) documentation. -You MUST write +You SHOULD write [commit messages that make sense](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). You MUST [rebase your branch](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) before submitting your Pull Request.