Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a section about versioning to the meta document #62

Merged
merged 4 commits into from
Mar 1, 2023
Merged

Add a section about versioning to the meta document #62

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
51f92d3
Add a section about versioning
lpd-au Feb 18, 2023
4a91c66
Update versioning section
lpd-au Feb 26, 2023
b39f7cf
Be more clear about minor version compatibility
lpd-au Feb 26, 2023
c34f7f6
Update meta.md
lpd-au Feb 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 49 additions & 19 deletions meta.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -57,12 +57,42 @@ 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 this PER, such as fixing typos, adding clarifications or
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 more permissive and backwards compatible for implementers.
* **Major** versions may additionally:
* 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 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
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

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
Expand All @@ -71,25 +101,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 |
| -------------- | ------- | ---------------------------------------------------- | ---------------------------------- | ----------------------------------------- | ------------------------------------------- | -------------------------------------------------------- | ------------------------------- | ------------------------------------- |------------------------------- |------------------------------------ | ----------------------------------- | ---------------------- |--------------------------- | ----------------------------------- | --------------------------- | -------------------------- |
Expand All @@ -111,7 +141,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 |
| -------- | --- | ------- | -------------- |
Expand All @@ -131,7 +161,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
Expand All @@ -140,13 +170,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
Expand All @@ -165,7 +195,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
Expand All @@ -176,33 +206,33 @@ 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
* Larry Garfield
* 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._

Expand Down