From 51f92d36b5960e7a7524ec34b6804cd34d89178a Mon Sep 17 00:00:00 2001 From: lpd-au Date: Sat, 18 Feb 2023 21:29:32 +1100 Subject: [PATCH 1/4] Add a section about versioning --- meta.md | 57 ++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 19 deletions(-) diff --git a/meta.md b/meta.md index 0eabf9b..7a26f05 100644 --- a/meta.md +++ b/meta.md @@ -26,7 +26,7 @@ To help alleviate this issue with PSR-12, we have taken a more prescriptive appr defined the standards for new language features as they are released. However, it is for a lack of wanting to be dictatorial that we aimed to apply PSR-2 -styling, rationale and stances (Described in Section 4, Approaches) in PSR-12 instead of +styling, rationale and stances (Described in Section 5, Approaches) in PSR-12 instead of establishing new conventions. The same approach is applied to the current PER. @@ -57,12 +57,31 @@ PSR-12. It is not the intention of this PER to add entirely new coding style guidelines. It will also not change anything stipulated in PSR-1 and PSR-12. -## 4. Approaches +## 4. Versioning + +New releases of this PER are assigned version numbers in keeping with [semantic versioning](https://semver.org/). Semantic versioning is well defined when applied to software releases but has no common definition in other contexts. This PER applies the following meanings: + +* **Patch** versions may contain: + * Any changes that do not alter the underlying requirements of the PER, such as fixing typos, adding clarifications or other modifications with no compatibility impact. +* **Minor** versions may additionally: + * Add new `MAY` or `OPTIONAL` requirements. + * Add any new requirements for PHP syntax previously unspecified in this PER. + * Remove `MUST NOT`, `SHALL NOT`, `SHOULD NOT` or `NOT RECOMMENDED` requirements. +* **Major** versions may additionally: + * Add any new requirements. + * Remove any requirements. + * Meaningfully alter any requirements. + +Projects are expected to pin their own coding style guidelines to a major version of this PER, allowing for regular upgrades to minor and patch releases as they are published. When performing such upgrades, it is intended that no change to existing code is required to maintain compliance with all requirements and recommendations of the PER. This ensures new code contributions processed by an automatic formatter follow (or disregard) recommendations consistently with the existing code. + +Please note this backwards compatibility promise does not extend to projects that use new PHP syntax yet to be specified in this PER. In this circumstance, a minor version may introduce new requirements that conflict with syntax usage in existing code. + +## 5. Approaches The overarching approach is to attempt to apply existing PSR-12 styling and rationale to new functionality as opposed to establishing new conventions. -### 4.1. Strict Types Declarations +### 5.1. Strict Types Declarations There was a discussion about whether strict types should be enforced in the standard https://github.com/cs-extended/fig-standards/issues/7. All were in agreement we should only @@ -71,25 +90,25 @@ to say that strict types could not be declared. The discussion was whether it sh considered a coding style item which should be covered or whether it was out of scope, and it was decided to be out of scope of a coding style guide. -### 4.2. Finally and Return Types Declaration Spacing +### 5.2. Finally and Return Types Declaration Spacing Numerous options were suggested, and they can be seen [here for return type declarations](https://gist.github.com/michaelcullum/c025f3870c9ea1dd2668#file-returntypesspacing-php) or [here for finally blocks](https://gist.github.com/michaelcullum/c025f3870c9ea1dd2668#file-finallyblocks-php) and the current implementation was chosen due to consistency with other parts of the standard. -### 4.3. Enforcing short form for all type keywords +### 5.3. Enforcing short form for all type keywords PHP 7.0 introduced [scalar types declaration](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) which does not support long type aliases. Therefore, it makes sense to enforce primary short type forms to be used to have uniform syntax and prevent possible confusion. -### 4.4. Public Survey +### 5.4. Public Survey In order to settle things using data, survey was conducted and responses from 142 people including 17 project representatives were gathered: -#### 4.4.1. PHP-FIG Representative Results +#### 5.4.1. PHP-FIG Representative Results | Representative | Project | Compound namespaces with a depth of two or more MUST not be used | Header statement grouping and ordering | Declare statements must each be on their own line | Declare statements in PHP files containing markup | Declare statements have no spaces: `declare(strict_types=1);` | Block declare statement formatting | `new` keyword usage, parenthesis required |Return type declaration formatting |Use statement leading slashes disallowed | Block namespace declaration formatting | General operator spacing |Try, Catch, Finally formatting | Anonymous class declaration formatting | Keyword casing, only lower case | Type keywords, short form only | | -------------- | ------- | ---------------------------------------------------- | ---------------------------------- | ----------------------------------------- | ------------------------------------------- | -------------------------------------------------------- | ------------------------------- | ------------------------------------- |------------------------------- |------------------------------------ | ----------------------------------- | ---------------------- |--------------------------- | ----------------------------------- | --------------------------- | -------------------------- | @@ -111,7 +130,7 @@ including 17 project representatives were gathered: | Chuck Burgess | PEAR | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | **Totals**: |13/3|15/1|15/1|13/3|14/2|15/1|14/2|15/1|14/2|14/2|15/1|16/0|15/1|15/1|15/1| -#### 4.4.2. General non-representative voters +#### 5.4.2. General non-representative voters | Question | For | Against | Percentage For | | -------- | --- | ------- | -------------- | @@ -131,7 +150,7 @@ including 17 project representatives were gathered: | Keyword casing, only lower case | 124 | 2 | 98.39% | | Type keywords, short form only | 121 | 5 | 95.87% | -### 4.5. Multiline Function Arguments Mixed With Multiline Return +### 5.5. Multiline Function Arguments Mixed With Multiline Return A potential readability issue [was raised on the mailing list](https://groups.google.com/d/msg/php-fig/ULSL4gqK8GY/cgDELuPOCQAJ). We reviewed options for changes to the specification that could provide better readability and @@ -140,13 +159,13 @@ arguments and the return are both multiline. Instead, it was pointed out that th _already_ allows you to decide where you'd like to add blank lines, and so we will leave it to the implementors to decide. -## 5. Changelog +## 6. Changelog Please note this changelog is not a verbose list of changes from PSR-12 and further but highlights the most notable changes. It should be considered a new specification, and therefore you should read the specification for a full understanding of its contents. -### 5.1. New Statements +### 6.1. New Statements * Lowercase for all keywords - Section 2.5 * Short form for all type keywords - Section 2.5 @@ -165,7 +184,7 @@ specification for a full understanding of its contents. * Ternary operators - Section 6.3 * Anonymous classes - Section 8 -### 5.2. Clarifications and Errata +### 6.2. Clarifications and Errata * Adjust 'methods' to 'methods and functions' in a number of instances - Throughout * Adjust references to classes and interfaces to also include traits - Throughout @@ -176,17 +195,17 @@ specification for a full understanding of its contents. * PSR-2 errata statement about extending multiple interfaces - Section 4 * Forbid blank lines before/after closing/opening braces for classes - Section 4 -## 6. People +## 7. People -### 6.1. Editor: +### 7.1. Editor: * Korvin Szanto -### 6.2. Sponsor: +### 7.2. Sponsor: * Chris Tankersley -### 6.3. Working Group Members: +### 7.3. Working Group Members: * Alexander Makarov * Ken Guest @@ -194,15 +213,15 @@ specification for a full understanding of its contents. * Luke Diggins * Woody Gilk -### 6.4. Special Thanks +### 7.4. Special Thanks * Everyone involved in PSR-1, PSR-2, PSR-12. -## 7. Votes +## 8. Votes * **Entrance Vote:** https://groups.google.com/g/php-fig/c/YqPDYGK0RhM/m/pJmThkNKBgAJ -## 8. Relevant Links +## 9. Relevant Links _**Note:** Order descending chronologically._ From 4a91c6681c7d14ca79ae91329160a700361ba839 Mon Sep 17 00:00:00 2001 From: lpd-au Date: Mon, 27 Feb 2023 00:59:27 +1100 Subject: [PATCH 2/4] Update versioning section Included feedback from korvin --- meta.md | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/meta.md b/meta.md index 7a26f05..46d1f45 100644 --- a/meta.md +++ b/meta.md @@ -59,22 +59,35 @@ also not change anything stipulated in PSR-1 and PSR-12. ## 4. Versioning -New releases of this PER are assigned version numbers in keeping with [semantic versioning](https://semver.org/). Semantic versioning is well defined when applied to software releases but has no common definition in other contexts. This PER applies the following meanings: +New releases of this PER are assigned version numbers in keeping with [semantic versioning](https://semver.org/). +Semantic versioning is well defined when applied to software releases but has no common definition in other contexts. +This PER applies the following meanings: * **Patch** versions may contain: - * Any changes that do not alter the underlying requirements of the PER, such as fixing typos, adding clarifications or other modifications with no compatibility impact. + * Any changes that do not alter the underlying requirements of this PER, such as fixing typos, adding clarifications or +other modifications with no compatibility impact. * **Minor** versions may additionally: - * Add new `MAY` or `OPTIONAL` requirements. - * Add any new requirements for PHP syntax previously unspecified in this PER. - * Remove `MUST NOT`, `SHALL NOT`, `SHOULD NOT` or `NOT RECOMMENDED` requirements. + * Add new requirements for PHP syntax previously unspecified in this PER. + * Add, remove or alter requirements in a way that is both contravariant or more permissive for individual authors and +backwards compatible for existing projects accepting contributions. * **Major** versions may additionally: - * Add any new requirements. - * Remove any requirements. - * Meaningfully alter any requirements. - -Projects are expected to pin their own coding style guidelines to a major version of this PER, allowing for regular upgrades to minor and patch releases as they are published. When performing such upgrades, it is intended that no change to existing code is required to maintain compliance with all requirements and recommendations of the PER. This ensures new code contributions processed by an automatic formatter follow (or disregard) recommendations consistently with the existing code. - -Please note this backwards compatibility promise does not extend to projects that use new PHP syntax yet to be specified in this PER. In this circumstance, a minor version may introduce new requirements that conflict with syntax usage in existing code. + * Add, remove or alter any requirements. + +Projects are expected to pin their own coding style guidelines to a major version of this PER, allowing for regular +upgrades to minor and patch releases as they are published. When performing such upgrades, it is intended that no change +to existing code is required to maintain compliance with all requirements and recommendations of this PER. This ensures +new code contributions processed by an automatic formatter follow (or disregard) recommendations consistently with the +existing code. + +Please note this backwards compatibility promise does not extend to projects that use new PHP syntax yet to be specified +in this PER. In this circumstance, a minor version may introduce new requirements that conflict with syntax usage in +existing code. + +It is ultimately determined whether a meaningful change may be included in a minor release on a case-by-case basis by +consensus. The addition of `MAY` or `OPTIONAL` requirements or the removal of requirements with non-optional RFC 2119 +keywords will not always meet the criteria for minor release. For example, specifying that projects may use tabs instead +of spaces for indentation creates a new implicit requirement that projects must use one style consistently; this new +burden on projects to reformat incoming contributions to their chosen style defines the change as major. ## 5. Approaches From b39f7cf7fae37cad62aa092f40b9b2a2ebd3e561 Mon Sep 17 00:00:00 2001 From: lpd-au Date: Mon, 27 Feb 2023 01:05:14 +1100 Subject: [PATCH 3/4] Be more clear about minor version compatibility --- meta.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/meta.md b/meta.md index 46d1f45..bac4594 100644 --- a/meta.md +++ b/meta.md @@ -80,8 +80,7 @@ new code contributions processed by an automatic formatter follow (or disregard) existing code. Please note this backwards compatibility promise does not extend to projects that use new PHP syntax yet to be specified -in this PER. In this circumstance, a minor version may introduce new requirements that conflict with syntax usage in -existing code. +in this PER. In this circumstance, a minor version may introduce new requirements that are effectively breaking changes. It is ultimately determined whether a meaningful change may be included in a minor release on a case-by-case basis by consensus. The addition of `MAY` or `OPTIONAL` requirements or the removal of requirements with non-optional RFC 2119 From c34f7f6219a4f0bbdbccec0885770f3a5540094a Mon Sep 17 00:00:00 2001 From: lpd-au Date: Wed, 1 Mar 2023 00:06:36 +1100 Subject: [PATCH 4/4] Update meta.md Co-authored-by: Korvin Szanto --- meta.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/meta.md b/meta.md index bac4594..4335606 100644 --- a/meta.md +++ b/meta.md @@ -68,8 +68,7 @@ This PER applies the following meanings: other modifications with no compatibility impact. * **Minor** versions may additionally: * Add new requirements for PHP syntax previously unspecified in this PER. - * Add, remove or alter requirements in a way that is both contravariant or more permissive for individual authors and -backwards compatible for existing projects accepting contributions. + * Add, remove or alter requirements in a way that is both more permissive and backwards compatible for implementers. * **Major** versions may additionally: * Add, remove or alter any requirements.