[RFC][Discussion] Policy release process update

15 days ago by Jakub Zelenka — view source

unread

Hello,

I'd like to start discussion for some release process updates defined in
the following RFC / linked PR:

RFC: https://wiki.php.net/rfc/policy-release-process-update
Policy PR: https://github.com/php/policies/pull/19

Regards

Jakub

15 days ago by tim@bastelstu.be — view source

unread

Am 2025-05-09 12:47, schrieb Jakub Zelenka:

I'd like to start discussion for some release process updates defined
in
the following RFC / linked PR:

RFC: https://wiki.php.net/rfc/policy-release-process-update
Policy PR: https://github.com/php/policies/pull/19

Thank you. The changes seem to accurately reflect the current practice
and make sense to me. I however noticed that “Major” and “Minor”
versions both effectively have the same allowances. Perhaps we could add
some additional nuance as to what breaking changes are allowed to be
approved by an RFC in a minor version, since breaking changes in majors
should also require an RFC. Some thoughts:

A minor version MUST NOT break syntax compatibility (i.e. every PHP
program that compiles must continue to compile).
Breaking changes in minor versions SHOULD be limited to extensions /
the API of functions within an extension.
The addition of deprecations themselves is not considered a breaking
change (to resolve the discussion that comes up for each and every
bulk-deprecation RFC, when you convert Deprecations into Exceptions
that's on you).
The addition of new symbols (e.g. functions or classes) might conflict
with user-defined classes, but this is not considered a breaking change.
An RFC should make a best effort to minimize the impact of a new
function name by choosing among equally good names (but not
unnecessarily choose a worse name, just because it is less likely to
break). This is already implied by it being legal to add features
without an RFC, but would be good to spell out explicitly.

Best regards
Tim Düsterhus

15 days ago by Jakub Zelenka — view source

unread

Hi,

Hi

Am 2025-05-09 12:47, schrieb Jakub Zelenka:

I'd like to start discussion for some release process updates defined
in
the following RFC / linked PR:

RFC: https://wiki.php.net/rfc/policy-release-process-update
Policy PR: https://github.com/php/policies/pull/19

Thank you. The changes seem to accurately reflect the current practice
and make sense to me. I however noticed that “Major” and “Minor”
versions both effectively have the same allowances. Perhaps we could add
some additional nuance as to what breaking changes are allowed to be
approved by an RFC in a minor version, since breaking changes in majors
should also require an RFC.

Yeah it doesn't make much sense to note that RFC bit. I wanted to say that
breaks
are possible as it's already happening but the wording was not the best.

Some thoughts:

A minor version MUST NOT break syntax compatibility (i.e. every PHP
program that compiles must continue to compile).

Added this one

Breaking changes in minor versions SHOULD be limited to extensions /
the API of functions within an extension.

I'm not sure about this wording but it's better than it was before so used
that
as well.

The addition of deprecations themselves is not considered a breaking
change (to resolve the discussion that comes up for each and every
bulk-deprecation RFC, when you convert Deprecations into Exceptions
that's on you).

So this would probably require the full definition of BC break and list this
as part of it. It might need more point though. I will think about it and
try to
integrate it somehow.

The addition of new symbols (e.g. functions or classes) might conflict
with user-defined classes, but this is not considered a breaking change.
An RFC should make a best effort to minimize the impact of a new
function name by choosing among equally good names (but not
unnecessarily choose a worse name, just because it is less likely to
break). This is already implied by it being legal to add features
without an RFC, but would be good to spell out explicitly.

Another point for the BC break definition I think.

Kind regards,

Jakub

13 days ago by tim@bastelstu.be — view source

unread

I gave this some additional thoughts.

Am 2025-05-09 13:36, schrieb Jakub Zelenka:

A minor version MUST NOT break syntax compatibility (i.e. every PHP
program that compiles must continue to compile).

Added this one

Thinking about this more, I am not sure if having this as a MUST rule
matches what we did in the past and I'm also not sure if it is useful to
have. This rule prevents the addition of new keywords, since they might
conflict with function names. Adding new symbols and adding a new
keyword is functionally equivalent, both changes would result in a
compile time error. Singling out the syntax change does not appear to be
a useful distinction.

From my experience in maintaining an old PHP application and upgrading
it to support the latest and greatest PHP every year, I think the
following points would be a good starting point to discuss:

For backwards compatibility breaks introduced in minor versions there
MUST be a simple (for some appropriate definition of simple) way to
adjust the code to be compatible with both the current PHP version and
the upcoming version. Ideally the change would be compatible with a
wider range of past PHP versions (past 3 or so?). It must be a change
that is simple to perform even with basic tooling (i.e. not requiring an
IDE or static analyzers).
Backwards compatibility breaks in minor versions MUST NOT result in
silent behavioral differences. Instead any breaking change must be
"obvious" when executing the program, even when having a
less-than-stellar test suite.

Adding new symbols results in a compile time error (immediately obvious)
and is simple to fix (rename or remove your own implementation).
Similarly throwing a ValueError for invalid inputs is reasonably easy to
detect by executing the affected code path (you can't miss an Exception)
and also simple to fix (don't do that). Changing operator precedence is
not easy to detect, thus it is unacceptable. Throwing an error when
single-letter variables (e.g. $i) would be easy to detect, but break
almost every program, thus would be unacceptable.

Best regards
Tim Düsterhus

11 days ago by Jakub Zelenka — view source

unread

Hi,

Hi

I gave this some additional thoughts.

Am 2025-05-09 13:36, schrieb Jakub Zelenka:

A minor version MUST NOT break syntax compatibility (i.e. every PHP
program that compiles must continue to compile).

Added this one

Thinking about this more, I am not sure if having this as a MUST rule
matches what we did in the past and I'm also not sure if it is useful to
have. This rule prevents the addition of new keywords, since they might
conflict with function names. Adding new symbols and adding a new
keyword is functionally equivalent, both changes would result in a
compile time error. Singling out the syntax change does not appear to be
a useful distinction.

Yeah this make sense. I changed it to SHOULD in the latest version with
some other updates.

From my experience in maintaining an old PHP application and upgrading
it to support the latest and greatest PHP every year, I think the
following points would be a good starting point to discuss:

For backwards compatibility breaks introduced in minor versions there
MUST be a simple (for some appropriate definition of simple) way to
adjust the code to be compatible with both the current PHP version and
the upcoming version. Ideally the change would be compatible with a
wider range of past PHP versions (past 3 or so?). It must be a change
that is simple to perform even with basic tooling (i.e. not requiring an
IDE or static analyzers).

If I understand it correctly, this sounds really more like completely new
rule that we don't currently have so I would rather not add it. We don't
have this relation differences between X.Y and X.(Y+2) to do some extra
breaks so it's more for a separate RFC. I'm also not a big fan of such
change to be honest.

Backwards compatibility breaks in minor versions MUST NOT result in
silent behavioral differences. Instead any breaking change must be
"obvious" when executing the program, even when having a
less-than-stellar test suite.

I think this makes sense and added this paragraph (with exception of that
less-than-stellar test suite) to the policy.

Adding new symbols results in a compile time error (immediately obvious)
and is simple to fix (rename or remove your own implementation).
Similarly throwing a ValueError for invalid inputs is reasonably easy to
detect by executing the affected code path (you can't miss an Exception)
and also simple to fix (don't do that). Changing operator precedence is
not easy to detect, thus it is unacceptable. Throwing an error when
single-letter variables (e.g. $i) would be easy to detect, but break
almost every program, thus would be unacceptable.

This makes sense but might be a bit too specific. Did you mean to also
include it in this policy?

Kind regards

Jakub

11 days ago by tim@bastelstu.be — view source

unread

Am 2025-05-13 12:13, schrieb Jakub Zelenka:

From my experience in maintaining an old PHP application and
upgrading
it to support the latest and greatest PHP every year, I think the
following points would be a good starting point to discuss:

For backwards compatibility breaks introduced in minor versions
there
MUST be a simple (for some appropriate definition of simple) way to
adjust the code to be compatible with both the current PHP version and
the upcoming version. Ideally the change would be compatible with a
wider range of past PHP versions (past 3 or so?). It must be a change
that is simple to perform even with basic tooling (i.e. not requiring
an
IDE or static analyzers).

If I understand it correctly, this sounds really more like completely
new
rule that we don't currently have so I would rather not add it. We
don't
have this relation differences between X.Y and X.(Y+2) to do some extra
breaks so it's more for a separate RFC. I'm also not a big fan of such
change to be honest.

We don't currently have any rules at all, except for “when the RFC
approves the break, then it's okay”. I was trying to find some guideline
for BC breaks that might be okay in a minor (when approved) and BC
breaks that are never okay in a minor.

The application in question is in a very similar position that PHP
itself is, it has a large public API that "third party" developers rely
on and a long development history. BC breaks sometimes are not avoidable
when you try to move forward. Basically the rule of thumb for a breaking
change in a minor version was that "most third party add-on should be
adaptable with minimal changes, while remaining compatible with both
minor versions after making these minimal changes".

Adding new symbols results in a compile time error (immediately
obvious)
and is simple to fix (rename or remove your own implementation).
Similarly throwing a ValueError for invalid inputs is reasonably easy
to
detect by executing the affected code path (you can't miss an
Exception)
and also simple to fix (don't do that). Changing operator precedence
is
not easy to detect, thus it is unacceptable. Throwing an error when
single-letter variables (e.g. $i) would be easy to detect, but break
almost every program, thus would be unacceptable.

This makes sense but might be a bit too specific. Did you mean to also
include it in this policy?

That paragraph is intended as an example for my train of thought / how I
would interpret my suggested guidelines for hypothetical breaking
changes. Of course I do not expect anyone to propose an RFC to disallow
single-letter variables (not even in a major).

Best regards
Tim Düsterhus

11 days ago by Jakub Zelenka — view source

unread

Hi,

Hi

Am 2025-05-13 12:13, schrieb Jakub Zelenka:

From my experience in maintaining an old PHP application and
upgrading
it to support the latest and greatest PHP every year, I think the
following points would be a good starting point to discuss:

For backwards compatibility breaks introduced in minor versions
there
MUST be a simple (for some appropriate definition of simple) way to
adjust the code to be compatible with both the current PHP version and
the upcoming version. Ideally the change would be compatible with a
wider range of past PHP versions (past 3 or so?). It must be a change
that is simple to perform even with basic tooling (i.e. not requiring
an
IDE or static analyzers).

If I understand it correctly, this sounds really more like completely
new
rule that we don't currently have so I would rather not add it. We
don't
have this relation differences between X.Y and X.(Y+2) to do some extra
breaks so it's more for a separate RFC. I'm also not a big fan of such
change to be honest.

We don't currently have any rules at all, except for “when the RFC
approves the break, then it's okay”. I was trying to find some guideline
for BC breaks that might be okay in a minor (when approved) and BC
breaks that are never okay in a minor.

What I meant is that this would be quite significant change as it could
lead to some sort of bigger breaks when people could think that introducing
break after few years is ok. That's how I understood it but thinking about
it, it would be probably fine if it was an additional restriction (meaning
we would still keep "Syntax backward compatibility SHOULD be preserved").
It would need some good formulation though. So if you can come up with
something that is clear, I would be happy to add it.

The application in question is in a very similar position that PHP
itself is, it has a large public API that "third party" developers rely
on and a long development history. BC breaks sometimes are not avoidable
when you try to move forward. Basically the rule of thumb for a breaking
change in a minor version was that "most third party add-on should be
adaptable with minimal changes, while remaining compatible with both
minor versions after making these minimal changes".

I understand what you mean. The only challenge is to find a good wording to
the policy. :)

Kind regards

Jakub

10 days ago by Jorg Sowa — view source

unread

Thank you Jakub for tackling the problem of inconsistency between policy
and practice.

Taking my PR as case study, under this policy I am allowed to choose
whatever approach I want? Either deprecation or validation error.
https://github.com/php/php-src/pull/15647

Behavior changes in undefined or undocumented edge cases MAY be
allowed if
well justified. However, care SHOULD be taken to minimize disruption.

Kind regards,
Jorg