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.

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

Add a section about versioning to the meta document #62

Merged
merged 4 commits into from
Mar 1, 2023

Conversation

lpd-au
Copy link
Contributor

@lpd-au lpd-au commented Feb 26, 2023

Resolves #10

What

This pull request adds a section to the meta document about versioning. It states that we use semantic versioning, details how semantic versioning is being applied to a text document rather than the usual software api, explains the rationale for that interpretation, gives a concrete example of that interpretation being applied to a hypothetical change and warns readers about the possibility of breaking changes in minor versions when using new PHP features before this PER standardises their style. Compared to the initial draft I shared in discord or the original comment in #10, it is less prescriptive about RFC 2119 keywords and more focused on the outcome for authors and projects.

Why at all?

The PER workflow bylaws state that votes must be held for new releases that would be minor or major according to semantic versioning. Importantly, to my reading, it does not require that the releases themselves must be labelled according to semver; it would be equally valid to have release numbers that eg match php releases, provided votes are still held at the required times. Even if the bylaws did require that, they aren't an obvious place to look for spec readers. This addition makes it abundently clear we follow semver.

As written in the proposed section, semver is well defined when applied to software releases but has no common definition in other contexts. Even within the working group, our first instincts on how semver applies to a coding guidelines standard weren't a perfect match. In particular, the potential for breaking changes in minor versions if you use PHP features undocumented in the spec isn't necessarily intuitive. This section aims to convey to readers a high level understanding that is consistent with our current understanding, recognising we can't predict the low level nuance of every future change in advance.

Why now?

Excluding 1.0 as a clone of PSR-12, this is effectively the first substantial release of any PER. How we handle releases is to me a critical process issue, both for ourselves and in establishing a precedent/example for future PERs. In my opinion, it is insufficient for an open github issue (especially with unresolved working group comments) to fulfil the role of documenting this critical process because:

  1. It has low visibility to consumers of the spec.
  2. The text is subject to change without notice.
  3. The text has never been put to a working group vote.
  4. The text is unenforcable.
  5. It ignores best practice to document such decisions in the meta document.

Including this PR now, or an alternative wording, will:

  1. Increase visibility to readers of the spec.
  2. Formalise whatever guarantees we are prepared to offer consumers of the spec about minor and patch releases, and ensure the text cannot be changed unilaterally or without notice.
  3. Demonstrate that the text represents the working group consensus, once 2.0 is accepted.
  4. Bind us to either follow the text or follow proper processes to change the text, while working on 2.x/3.0 and beyond.
  5. Ensure every substantial release of this PER has this critical process defined and set a positive example of best practice to future PERs.

meta.md Outdated Show resolved Hide resolved
@KorvinSzanto
Copy link
Contributor

I had one suggestion but this looks good to me otherwise, thank you!

Co-authored-by: Korvin Szanto <Korvinszanto@gmail.com>
@KorvinSzanto KorvinSzanto merged commit a6cf20a into php-fig:master Mar 1, 2023
@lpd-au lpd-au deleted the meta-versioning branch March 1, 2023 18:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Versioning
3 participants