From b2e17f75fe5d2e04f2f82fdb3993e2be50175f8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Machulda?= Date: Tue, 14 May 2024 10:46:02 +0200 Subject: [PATCH 1/2] Docs: Warn about thoughtless approving of risky changes --- UPGRADE-4.0.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/UPGRADE-4.0.md b/UPGRADE-4.0.md index 48b1a87..82dec8f 100644 --- a/UPGRADE-4.0.md +++ b/UPGRADE-4.0.md @@ -85,7 +85,20 @@ $ vendor/bin/ecs check --ansi src/ tests/ # old $ vendor/bin/ecs check --ansi # new ``` -### 5. Sanity check +### 5. BE CAREFUL WITH SUGGESTED CHANGES! ⚠️ + +Some of the new default fixers introduced in php-coding-standard 4.0 and 4.1 suggest changes, which - if not +thoughtfully reviewed - can change the code behavior. Especially changes introduced by (but not limited to!): + +- PhpdocToPropertyTypeFixer + PropertyTypeHintSniff +- PhpdocToParamTypeFixer + ParameterTypeHintSniff +- PhpdocToReturnTypeFixer + ReturnTypeHintSniff + +**Always carefully review the changes suggested by all fixers!** You may want to skip some of the checks +(using `withSkip()`) in the first phase of upgrading to the new version of the coding standard +or you can introduce some of the rules gradually or on a file-by-file basis. + +### 6. Sanity check Besides running your code style checks, you can ensure all predefined checks are loaded as well, by running: ```sh From 93f588d08b7a6bca3723759f3f4816641089fdbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Machulda?= Date: Tue, 14 May 2024 11:05:46 +0200 Subject: [PATCH 2/2] Docs: Make grammar and structure improvements in readme and upgrade guide --- README.md | 27 ++++++++++++++++----------- UPGRADE-4.0.md | 10 +++++----- 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 5b57997..62e17be 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,12 @@ [![Latest Stable Version](https://img.shields.io/packagist/v/lmc/coding-standard.svg?style=flat-square)](https://packagist.org/packages/lmc/coding-standard) -PHP coding standard used in [Alma Career Czechia](https://www.almacareer.com/) (formerly LMC) products. +PHP coding standard used in [Alma Career Czechia][Alma Career] (formerly LMC) products. -Standard is based on [PSR-12](https://www.php-fig.org/psr/psr-12/) and adds +The standard is based on [PSR-12][psr-12] and partially [PER 2.0][per-2] and adds various checks to make sure the code is readable, follows the same conventions, and does not contain common mistakes. -We use [EasyCodingStandard] to define and execute checks created for both [PHP-CS-Fixer] and [PHP_CodeSniffer]. +We use [EasyCodingStandard][ecs] to define and execute checks created for both [PHP-CS-Fixer] and [PHP_CodeSniffer]. ## Installation @@ -59,7 +59,7 @@ Now you will be able to run the fix using `composer analyze` and execute automat ### Add custom checks or override default settings -On top of default code-style rules you are free to add any rules from [PHP-CS-Fixer] or [PHP_CodeSniffer]. +On top of the default code-style rules, you are free to add any rules from [PHP-CS-Fixer] or [PHP_CodeSniffer]. If needed, you can also override some default settings. ```php @@ -83,12 +83,12 @@ return ECSConfig::configure() /* (...) */ ``` -See [EasyCodingStandard docs](https://github.com/symplify/easy-coding-standard#configuration) for more configuration options. +See [EasyCodingStandard docs][ecs-docs] for more configuration options. ### Exclude (skip) checks or files -You can configure your `ecs.php` to entirely skip some files, disable specific checks or suppress specific errors. +You can configure your `ecs.php` file to entirely skip some files, disable specific checks, or suppress specific errors. ```php