Versioning

[KorvinSzanto]

I wanted to clearly define what "major" "minor" and "patch" mean in the context of this PER and how we will handle versioning for v1.0.0 and after. This is an important thing to nail down because we only need core committee approval for major versions.

To make this easier to follow, let's split the available requirement keywords into two groups:

1. "MUST"s: MUST, REQUIRED or SHALL
2. "SHOULD"s: SHOULD, RECOMMEND, MAY, or OPTIONAL

• Major: Altered/added/removed MUSTs for already covered syntax and altered/removed SHOULDs
• Minor: Added SHOULDs and added MUSTs for new syntax
• Patch: Any small changes to text like typos, clarifications, and anything else that does not effect compatibility with any requirements

There are times when SHOULDs can be modified or even removed in backwards compatible ways and in those cases we may opt for a minor release rather than a major release, erring on the side of a major release (and therefore a core committee vote) whenever appropriate. This is all up for discussion so if folks have any disagreements please add comments here.

With all of that said version 1.0.0 will be effectively a "patch" change from PSR-12, all changes are done to align names and descriptions with this PER and no requirements have been altered/added/removed.

[samdark]

I think altered/removed SHOULDs needs to be moved to Minor becuase it is still optional requirement and, thus, original code will be compatible.

[KorvinSzanto]

I've updated the list to make added MUSTs for new syntax a minor change after discussion in discord.

I think altered/removed SHOULDs needs to be moved to Minor becuase it is still optional requirement and, thus, original code will be compatible.

Removing or altering SHOULDs can have the effect of breaking compatibility. Imagine removing this:

Argument lists MAY be split across multiple lines

Removing this or altering it in a substantial way would rise to a major change in my mind. That said, I mentioned that there are times when SHOULDs can be altered or removed in a way that doesn't effect compatibility and in those cases (and in all cases really) we will use this post as a starting point and determine which release level is appropriate at the time of release.

[samdark]

Removing MAY doesn't automatically add MUST NOT. It adds some degree of uncertainity but code stays valid both before and after the change.