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
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. 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
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/19Thank 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
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.
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
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
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.
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
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
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
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
The pull request incorporated some other additions and there are no further
open review requests. I just updated the RFC with the summary of all
changes. I plan to open voting early next month so if you have any
comments, please send them here or to the PR.
Kind regards,
Jakub
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/19The pull request incorporated some other additions and there are no
further open review requests. I just updated the RFC with the summary
of all changes. I plan to open voting early next month so if you have
any comments, please send them here or to the PR.Kind regards,
Jakub
My only pushback is not specific to this PR, but more that this PR would be a good time to address this existing gap:
Under Major Version releases
- Significant userland API backward compatibility breaks SHOULD be preceded
by the deprecation phase in the previous major version.
Right now, that deprecation phase could be as little as 15 months, or as long as 5-6 years (and counting). And when deprecating something, we have no idea how long it's going to be deprecated before it's removed. That's decided well after the fact, whenever it's decided (by whatever means) that PHP.next will be a major this time.
This is hostile for users, who do not know, and cannot know, how long they have to address deprecations. Things deprecated in 8.5 (of which there were many) could be removed as soon as November of 2026. Things deprecated in 8.1, however, have been deprecated for ~4-5 years now, and also could be removed in November of 2026.
I would very much like us to put more structure around deprecations, when they happen, and the release cycle to support that. Fixing the number of years between Majors would be ideal, as then everyone can plan better around deprecations. (Eg, we can say "no deprecations in the last minor of a series", to ensure all deprecations have at least a 2 year window to address.) As is, it's still largely guesswork for everyone.
--Larry Garfield
My only pushback is not specific to this PR, but more that this PR would be a good time to address this existing gap:
Under Major Version releases
- Significant userland API backward compatibility breaks SHOULD be preceded
by the deprecation phase in the previous major version.
Right now, that deprecation phase could be as little as 15 months, or as long as 5-6 years (and counting). And when deprecating something, we have no idea how long it's going to be deprecated before it's removed. That's decided well after the fact, whenever it's decided (by whatever means) that PHP.next will be a major this time.
This is hostile for users, who do not know, and cannot know, how long they have to address deprecations. Things deprecated in 8.5 (of which there were many) could be removed as soon as November of 2026. Things deprecated in 8.1, however, have been deprecated for ~4-5 years now, and also could be removed in November of 2026.
I would very much like us to put more structure around deprecations, when they happen, and the release cycle to support that. Fixing the number of years between Majors would be ideal, as then everyone can plan better around deprecations. (Eg, we can say "no deprecations in the last minor of a series", to ensure all deprecations have at least a 2 year window to address.) As is, it's still largely guesswork for everyone.
--Larry Garfield
I vehemently disagree with this proposed policy.
Either we move to a system where deprecations are removed in constant intervals, e.g. every 3 years like Python does regardless of what the version number is,
Or we continue our "semver-ish" policy where we only remove deprecations in major versions.
Users are not forced to upgrade to a new major version when it is released, and restricting when php-src can introduce deprecations is not something that is practically doable.
A bunch of deprecations were already pushed back from 8.0 to 8.1 because we were told deprecations in a brand new major release just adds extra friction, and now you are floating the idea of no deprecations in the last minor?
Deprecations are basically never planned, because most, if not all, of them are proposed after someone encounters an oddity in the language.
Contributing to php-src is not easy, and we already have lost contributors by telling them that they should have proposed X 2-3 years ago because "now" is inconvenient.
Any policy that aims to restrict when php-src can or cannot do something will get an automatic NO from me.
Best regards,
Gina P. Banyard
On Monday, 13 October 2025 at 19:42, Larry Garfield
larry@garfieldtech.com wrote:My only pushback is not specific to this PR, but more that this PR would be a good time to address this existing gap:
Under Major Version releases
- Significant userland API backward compatibility breaks SHOULD be preceded
by the deprecation phase in the previous major version.
Right now, that deprecation phase could be as little as 15 months, or as long as 5-6 years (and counting). And when deprecating something, we have no idea how long it's going to be deprecated before it's removed. That's decided well after the fact, whenever it's decided (by whatever means) that PHP.next will be a major this time.
This is hostile for users, who do not know, and cannot know, how long they have to address deprecations. Things deprecated in 8.5 (of which there were many) could be removed as soon as November of 2026. Things deprecated in 8.1, however, have been deprecated for ~4-5 years now, and also could be removed in November of 2026.
I would very much like us to put more structure around deprecations, when they happen, and the release cycle to support that. Fixing the number of years between Majors would be ideal, as then everyone can plan better around deprecations. (Eg, we can say "no deprecations in the last minor of a series", to ensure all deprecations have at least a 2 year window to address.) As is, it's still largely guesswork for everyone.
--Larry Garfield
I vehemently disagree with this proposed policy.
Either we move to a system where deprecations are removed in constant
intervals, e.g. every 3 years like Python does regardless of what the
version number is,
Or we continue our "semver-ish" policy where we only remove
deprecations in major versions.
Users are not forced to upgrade to a new major version when it is
released, and restricting when php-src can introduce deprecations is
not something that is practically doable.
A bunch of deprecations were already pushed back from 8.0 to 8.1
because we were told deprecations in a brand new major release just
adds extra friction, and now you are floating the idea of no
deprecations in the last minor?
Deprecations are basically never planned, because most, if not all, of
them are proposed after someone encounters an oddity in the language.
Contributing to php-src is not easy, and we already have lost
contributors by telling them that they should have proposed X 2-3 years
ago because "now" is inconvenient.Any policy that aims to restrict when php-src can or cannot do
something will get an automatic NO from me.Best regards,
Gina P. Banyard
There were like 3 or 4 proposals in my spitballing above. I am not wedded to any in particular: My point is that right now, the handling of deprecations and their scheduling is user-hostile. We should fix that. That may involve some inconveniences for Internals, but... everything is a tradeoff. If it's a small inconvenience in return for a much more predictable and reliable release cycle for users, then frankly that's a win.
The details I am flexible on and happy to discuss options.
--Larry Garfield
Hi,
On Mon, Oct 13, 2025 at 8:41 PM Larry Garfield larry@garfieldtech.com
wrote:
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/19The pull request incorporated some other additions and there are no
further open review requests. I just updated the RFC with the summary
of all changes. I plan to open voting early next month so if you have
any comments, please send them here or to the PR.Kind regards,
Jakub
My only pushback is not specific to this PR, but more that this PR would
be a good time to address this existing gap:Under Major Version releases
- Significant userland API backward compatibility breaks SHOULD be
preceded
by the deprecation phase in the previous major version.Right now, that deprecation phase could be as little as 15 months, or as
long as 5-6 years (and counting). And when deprecating something, we have
no idea how long it's going to be deprecated before it's removed. That's
decided well after the fact, whenever it's decided (by whatever means) that
PHP.next will be a major this time.This is hostile for users, who do not know, and cannot know, how long they
have to address deprecations. Things deprecated in 8.5 (of which there
were many) could be removed as soon as November of 2026. Things deprecated
in 8.1, however, have been deprecated for ~4-5 years now, and also could be
removed in November of 2026.I would very much like us to put more structure around deprecations, when
they happen, and the release cycle to support that. Fixing the number of
years between Majors would be ideal, as then everyone can plan better
around deprecations. (Eg, we can say "no deprecations in the last minor of
a series", to ensure all deprecations have at least a 2 year window to
address.) As is, it's still largely guesswork for everyone.
This is out of scope here. The main point of this document is to state what
we already do or do some minor clarification of the rules. This is,
however, quite contentious and should be separate to its own RFC.
Kind regards,
Jakub
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
Just wanted to give heads up that I plan to open voting tomorrow.
Kind regards,
Jakub
Hi
Am 2025-11-02 13:38, schrieb Jakub Zelenka:
Just wanted to give heads up that I plan to open voting tomorrow.
I'm seeing there were some additional comments on the GitHub PR:
https://github.com/php/policies/pull/19#pullrequestreview-3413485445
As I had noted on the PR before
(https://github.com/php/policies/pull/19#discussion_r2425684839) PRs are
a terrible medium of discussion. And especially when the list is not
actively kept in loop, folks will inevitably miss out on some of the
discussion. That's why I mostly refused to discuss my policy RFCs on
GitHub, instead asking folks to come to the mailing list - which is the
accepted official discussion medium of RFCs - to have everything in a
single location.
I appreciate that you provided plenty of heads up for folks to review
the text after the initial (long) GitHub discussion, but after your
announcement from https://news-web.php.net/php.internals/128819 I would
kindly request that the ongoing discussion is kept on the list so that
everyone has a chance to see it.
Best regards
Tim Düsterhus
Hi
Am 2025-11-02 13:38, schrieb Jakub Zelenka:
Just wanted to give heads up that I plan to open voting tomorrow.
I'm seeing there were some additional comments on the GitHub PR:
https://github.com/php/policies/pull/19#pullrequestreview-3413485445
As I had noted on the PR before
(https://github.com/php/policies/pull/19#discussion_r2425684839) PRs are
a terrible medium of discussion. And especially when the list is not
actively kept in loop, folks will inevitably miss out on some of the
discussion. That's why I mostly refused to discuss my policy RFCs on
GitHub, instead asking folks to come to the mailing list - which is the
accepted official discussion medium of RFCs - to have everything in a
single location.I appreciate that you provided plenty of heads up for folks to review
the text after the initial (long) GitHub discussion, but after your
announcement from https://news-web.php.net/php.internals/128819 I would
kindly request that the ongoing discussion is kept on the list so that
everyone has a chance to see it.
I think GH is good to shape the initial policy as it's easier to comment on
specific parts there but agree that the main discussion should happen on
the list once announced. But you need to ask the ones that are commenting
there. I was just replaying...
Kind regards,
Jakub
Hi
Am 2025-11-02 13:38, schrieb Jakub Zelenka:
Just wanted to give heads up that I plan to open voting tomorrow.
I'm seeing there were some additional comments on the GitHub PR:
https://github.com/php/policies/pull/19#pullrequestreview-3413485445
As I had noted on the PR before
(https://github.com/php/policies/pull/19#discussion_r2425684839) PRs are
a terrible medium of discussion. And especially when the list is not
actively kept in loop, folks will inevitably miss out on some of the
discussion. That's why I mostly refused to discuss my policy RFCs on
GitHub, instead asking folks to come to the mailing list - which is the
accepted official discussion medium of RFCs - to have everything in a
single location.I appreciate that you provided plenty of heads up for folks to review
the text after the initial (long) GitHub discussion, but after your
announcement from https://news-web.php.net/php.internals/128819 I would
kindly request that the ongoing discussion is kept on the list so that
everyone has a chance to see it.I think GH is good to shape the initial policy as it's easier to comment
on specific parts there but agree that the main discussion should happen on
the list once announced. But you need to ask the ones that are commenting
there. I was just replaying...
To bring the discussion back here, there were two concerns:
-
That
Internal API compatibility breaks are NOT RECOMMENDED.is not the
current practice. I always thought that it is our current practice to limit
the internal API breaks to minimum so we don't in general don't recommend
those. But if others disagree that it's our current practice, I'm happy to
remove it. Personally I think it's good to have such recommendation because
internal API breaks often delay the release usage if some important
extension does not get updated. We had a very good example in imagick. -
The already existing rule RM can "Decide which bug fixes can be applied
to a release, within the cases defined in this RFC" was questioned if it
should stay and if RM ever used it. I think it should stay because it's
good to have some rule about who can decide a potential disagreement
whether the bug should be merged to the specific branch. This part has been
already in policy so there's not much to do here.
Kind regards,
Jakub