From 5c06fe036d6c143ac4692c0ef6ca140b8eb385cb Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 1 Aug 2017 10:20:55 +0200 Subject: [PATCH 1/5] Mention and recommend to use PHP-CS-Fixer when contributing code --- contributing/code/standards.rst | 46 ++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index b324dfe7d73..5bbfca89c09 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -1,19 +1,32 @@ Coding Standards ================ -When contributing code to Symfony, you must follow its coding standards. To -make a long story short, here is the golden rule: **Imitate the existing -Symfony code**. Most open-source Bundles and libraries used by Symfony also -follow the same guidelines, and you should too. +Symfony code is contributed by thousands of developers around the world. To make +every piece of code look and feel familiar, Symfony defines some coding standards +that all contributions must follow. -Remember that the main advantage of standards is that every piece of code -looks and feels familiar, it's not about this or that being more readable. +These Symfony coding standards are based on the `PSR-0`_, `PSR-1`_, `PSR-2`_ and +`PSR-4`_ standards, so you may already know most of them. -Symfony follows the standards defined in the `PSR-0`_, `PSR-1`_, `PSR-2`_ and `PSR-4`_ -documents. +Making your Code Follow the Coding Standards +-------------------------------------------- -Since a picture - or some code - is worth a thousand words, here's a short -example containing most features described below: +Instead of reviewing your code manually, Symfony makes it simple to ensure that +your contributed code matches the expected code syntax. First, install the +`PHP-CS-Fixer tool`_ and then, run this command to fix any problem: + +.. code-block:: terminal + + $ php php-cs-fixer.phar fix /path/to/project --rules=@Symfony + +If you forget to run this command and make a pull request with any syntax issue, +our automated tools will warn you about that and will provide the solution. + +Symfony Coding Standards in Detail +---------------------------------- + +If you want to learn about the Symfony coding standards in detail, here's a +short example containing most features described below: .. code-block:: html+php @@ -122,7 +135,7 @@ example containing most features described below: } Structure ---------- +~~~~~~~~~ * Add a single space after each comma delimiter; @@ -181,7 +194,7 @@ Structure * Do not use spaces around ``[`` offset accessor and before ``]`` offset accessor. Naming Conventions ------------------- +~~~~~~~~~~~~~~~~~~ * Use camelCase, not underscores, for variable, function and method names, arguments; @@ -223,7 +236,7 @@ Service Naming Conventions * A group name uses the underscore notation. Documentation -------------- +~~~~~~~~~~~~~ * Add PHPDoc blocks for all classes, methods, and functions (though you may be asked to remove PHPDoc that do not add value); @@ -234,14 +247,17 @@ Documentation * Omit the ``@return`` tag if the method does not return anything; -* The ``@package`` and ``@subpackage`` annotations are not used. +* The ``@package`` and ``@subpackage`` annotations are not used; + +* Inline the ``@inheritdoc`` tag. License -------- +~~~~~~~ * Symfony is released under the MIT license, and the license block has to be present at the top of every PHP file, before the namespace. +.. _`PHP-CS-Fixer tool`: https://github.com/FriendsOfPHP/PHP-CS-Fixer .. _`PSR-0`: http://www.php-fig.org/psr/psr-0/ .. _`PSR-1`: http://www.php-fig.org/psr/psr-1/ .. _`PSR-2`: http://www.php-fig.org/psr/psr-2/ From a6fdc96f8e33d42237709a5ae62dcab56425edde Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 3 Aug 2017 09:46:15 +0200 Subject: [PATCH 2/5] Fixed all reported issues --- contributing/code/standards.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index 5bbfca89c09..8f13ef93156 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -5,19 +5,20 @@ Symfony code is contributed by thousands of developers around the world. To make every piece of code look and feel familiar, Symfony defines some coding standards that all contributions must follow. -These Symfony coding standards are based on the `PSR-0`_, `PSR-1`_, `PSR-2`_ and -`PSR-4`_ standards, so you may already know most of them. +These Symfony coding standards are based on the `PSR-1`_, `PSR-2`_ and `PSR-4`_ +standards, so you may already know most of them. Making your Code Follow the Coding Standards -------------------------------------------- Instead of reviewing your code manually, Symfony makes it simple to ensure that your contributed code matches the expected code syntax. First, install the -`PHP-CS-Fixer tool`_ and then, run this command to fix any problem: +`PHP CS Fixer tool`_ and then, run this command to fix any problem: .. code-block:: terminal - $ php php-cs-fixer.phar fix /path/to/project --rules=@Symfony + $ cd your-project/ + $ php php-cs-fixer.phar fix -v If you forget to run this command and make a pull request with any syntax issue, our automated tools will warn you about that and will provide the solution. From 7b3177360afcea161a22c92a2cef245678192dec Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 3 Aug 2017 09:53:31 +0200 Subject: [PATCH 3/5] Fixed the link --- contributing/code/standards.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index 8f13ef93156..05f2b564ada 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -258,7 +258,7 @@ License * Symfony is released under the MIT license, and the license block has to be present at the top of every PHP file, before the namespace. -.. _`PHP-CS-Fixer tool`: https://github.com/FriendsOfPHP/PHP-CS-Fixer +.. _`PHP CS Fixer tool`: https://github.com/FriendsOfPHP/PHP-CS-Fixer .. _`PSR-0`: http://www.php-fig.org/psr/psr-0/ .. _`PSR-1`: http://www.php-fig.org/psr/psr-1/ .. _`PSR-2`: http://www.php-fig.org/psr/psr-2/ From 30e9e3e8b70586a1e49e77cd82e519ed56afd466 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 3 Aug 2017 12:57:53 +0200 Subject: [PATCH 4/5] Fixed the command again --- contributing/code/standards.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index 05f2b564ada..822604ed529 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -18,7 +18,7 @@ your contributed code matches the expected code syntax. First, install the .. code-block:: terminal $ cd your-project/ - $ php php-cs-fixer.phar fix -v + $ php php-cs-fixer.phar fix /path/to/modified/file.php If you forget to run this command and make a pull request with any syntax issue, our automated tools will warn you about that and will provide the solution. From 5def3f1ce0359ca672968746c70dae1a903ac5ec Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 4 Jan 2018 10:47:31 +0100 Subject: [PATCH 5/5] Minor fixes --- contributing/code/standards.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index 822604ed529..96dfdc8d047 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -18,7 +18,7 @@ your contributed code matches the expected code syntax. First, install the .. code-block:: terminal $ cd your-project/ - $ php php-cs-fixer.phar fix /path/to/modified/file.php + $ php php-cs-fixer.phar fix -v If you forget to run this command and make a pull request with any syntax issue, our automated tools will warn you about that and will provide the solution. @@ -258,7 +258,7 @@ License * Symfony is released under the MIT license, and the license block has to be present at the top of every PHP file, before the namespace. -.. _`PHP CS Fixer tool`: https://github.com/FriendsOfPHP/PHP-CS-Fixer +.. _`PHP CS Fixer tool`: http://cs.sensiolabs.org/ .. _`PSR-0`: http://www.php-fig.org/psr/psr-0/ .. _`PSR-1`: http://www.php-fig.org/psr/psr-1/ .. _`PSR-2`: http://www.php-fig.org/psr/psr-2/