From ce21798bf303ff326ea133e2a0213b6a564ddc65 Mon Sep 17 00:00:00 2001 From: neznaika0 Date: Tue, 2 Sep 2025 10:33:26 +0300 Subject: [PATCH 1/2] docs: Update style recommendations --- contributing/pull_request.md | 4 ++++ contributing/styleguide.md | 1 + 2 files changed, 5 insertions(+) diff --git a/contributing/pull_request.md b/contributing/pull_request.md index 8e3b5ed9f419..0b9b8e0247c1 100644 --- a/contributing/pull_request.md +++ b/contributing/pull_request.md @@ -98,6 +98,10 @@ class/interface/trait, method, and variable. Do not add PHPDoc comments that are superficial, duplicated, or stating the obvious. +It is not recommended to reuse comments if the parent class or interface already contains a description of the child element. + +You can re-add a comment in a child element if it has a more precise type - i.e change `int|string` to `string`. + See the following for more information. - [PHPDoc reference](https://docs.phpdoc.org/3.0/guide/references/phpdoc/index.html#phpdoc-reference) diff --git a/contributing/styleguide.md b/contributing/styleguide.md index 95e68bb37ddb..1d57aa698358 100644 --- a/contributing/styleguide.md +++ b/contributing/styleguide.md @@ -241,6 +241,7 @@ of the classes they declare. - */ public function analyse(string $data): void {}; ``` +- SHOULD NOT duplicate comments from the parent class or interface. ### PHPUnit Assertions From 7dd9a8c4724a197772d0edb62dd7d1d035da4d1d Mon Sep 17 00:00:00 2001 From: neznaika0 Date: Fri, 5 Sep 2025 16:34:42 +0300 Subject: [PATCH 2/2] refactor: Add note about duplication phpDoc --- .github/PULL_REQUEST_TEMPLATE.md | 5 +++-- contributing/pull_request.md | 6 +----- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f16a793ece5b..e39d50b0b187 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -5,8 +5,9 @@ Each pull request should address a single issue and have a meaningful title. - PR title must include the type (feat, fix, chore, docs, perf, refactor, style, test) of the commit per Conventional Commits specification. See https://www.conventionalcommits.org/en/v1.0.0/ for the discussion. - Pull requests must be in English. - If a pull request fixes an issue, reference the issue with a suitable keyword (e.g., Fixes ). +- Your branch name and the target name should be different. - All bug fixes should be sent to the __"develop"__ branch, this is where the next bug fix version will be developed. -- PRs with any enhancement should be sent to the next minor version branch, e.g. __"4.5"__ +- PRs with any enhancement should be sent to the next minor version branch, e.g. __"4.7"__ --> **Description** @@ -14,7 +15,7 @@ Explain what you have changed, and why. **Checklist:** - [ ] Securely signed commits -- [ ] Component(s) with PHPDoc blocks, only if necessary or adds value +- [ ] Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication) - [ ] Unit testing, with >80% coverage - [ ] User guide updated - [ ] Conforms to style guide diff --git a/contributing/pull_request.md b/contributing/pull_request.md index 0b9b8e0247c1..b5db40417873 100644 --- a/contributing/pull_request.md +++ b/contributing/pull_request.md @@ -96,11 +96,7 @@ implementation comments to explain potentially confusing sections of code, and documentation comments before each public or protected class/interface/trait, method, and variable. -Do not add PHPDoc comments that are superficial, duplicated, or stating the obvious. - -It is not recommended to reuse comments if the parent class or interface already contains a description of the child element. - -You can re-add a comment in a child element if it has a more precise type - i.e change `int|string` to `string`. +Do not add PHPDoc comments that are superficial, duplicated, or stating the obvious. It is not recommended to reuse comments if the parent class or interface already contains a description of the child element. See the following for more information.