From 5e4a08cb759ad947beaa1bae4adf21cd8e613272 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Fri, 9 May 2025 12:10:13 +0200 Subject: [PATCH 01/22] Add changes to the release process This is to mostly match the current process and set some rules for it --- release-process.rst | 72 +++++++++++++++++++++++++++------------------ 1 file changed, 43 insertions(+), 29 deletions(-) diff --git a/release-process.rst b/release-process.rst index e8e7b8b..4dd4b17 100644 --- a/release-process.rst +++ b/release-process.rst @@ -52,9 +52,12 @@ Minor Version Number - Bugfixes - New features - Extensions support can be ended (moved to PECL) - - Backward compatibility must be kept - - API compatibility must be kept (userland) - - ABI and API can be broken (internals) + - Backward compatibility must be preserved unless explicitly broken by an + approved RFC. + - API compatibility for user-facing code must be preserved unless an RFC + explicitly allows a breaking change. + - ABI and internal API compatibility may be broken if necessary, without + requiring an RFC. - Source compatibility should be kept if possible, while breakages are allowed @@ -66,13 +69,19 @@ Patch Version Number - Bug fixes and security patches only - Extensions support can't be removed (like move them to PECL) - Backward compatibility must be kept (internals and userland) - - ABI and API compatibility must be kept (internals) + - ABI and internal API compatibility must be preserved, except in the case + of HIGH severity security issues where no other option is possible. It is critical to understand the consequences of breaking BC, APIs or ABIs (only internals related). It should not be done for the sake of doing it. RFCs explaining the reasoning behind a breakage and the consequences along with test cases and patch(es) should help. +If a HIGH severity security fix requires breaking the internal ABI or API, a +proper migration path must be provided, and the impact should be minimized as +much as possible. This should also be accompanied by additional communication +during the release. + See the following links for explanation about API and ABI: - http://en.wikipedia.org/wiki/Application_programming_interface @@ -228,9 +237,10 @@ After the general availability release: - Release only when there is a security issue or regression issue to address. - - Security fix and regression releases SHOULD occur on the same date as - bug fix releases for the other branches. Exceptions can be made for - high risk security issues or high profile regressions. + - Security fix, compatibility build fix and regression fix releases + SHOULD occur on the same date as bug fix releases for the other + branches. Exceptions can be made for high risk security issues or high + profile regressions. - Until the end of year 4 (e.g., for PHP 8.4: until Dec 31, 2028): @@ -238,9 +248,14 @@ After the general availability release: - Release only when there is a security issue. - - Security fix releases SHOULD occur on the same date as bug fix releases - for the other branches. Exceptions can be made for high risk security - issues. + - Security fix, compatibility build fix and regression fix releases + SHOULD occur on the same date as bug fix releases for the other + branches. Exceptions can be made for high risk security issues or high + profile regressions. + + - Regression fixes should be applied only exceptionally for small + regressions or regressions introduced by security fixes and it + should get RM approval. - Updates to ABI incompatible versions of dependent libraries on Windows are **not** performed. @@ -256,21 +271,26 @@ is Dec 31, 2026, 24:00 UTC, even if the actual release date slips to Jan 9, Feature selection and development *********************************** -RFCs have been introduced many years ago and have been proven as being an -amazing way to avoid conflicts while providing a very good way to propose new -things to php.net. New features or additions to the core should go through the -RFC process. It has been done successfully (as the process went well, but the -features were not necessary accepted) already for a dozen of new features or -improvements. +RFCs were introduced many years ago and have proven to be an effective way to +avoid conflicts while providing a structured process for proposing changes to +the PHP programming language. Most new features or core additions SHOULD go +through the RFC process. However, some features MAY be exempt, as described +below. The process has been used many times for proposing new features and +improvements, even when some proposals were ultimately not accepted. -Features can use branch(es) if necessary, doing so will minimize the impact of -other commits and changes on the development of a specific feature (or the other -way 'round). The shorter release cycle also ensures that a given feature can get -into the next release, as long as the RFC has been accepted. +New features MUST be implemented and proposed using a GitHub pull request. -The change to what we have now is the voting process. It will not happen anymore -on the mailing list but in the RFCs directly, for php.net members, in a public -way. +Internal API changes (those that do not affect the user-facing API), as well as +user-facing features in extensions and SAPIs, do not require an RFC unless a +core developer (someone with commit access to php-src) raises an objection or +requests an RFC within one month of the implementation pull request being +opened. A core developer MAY also request that the feature be discussed on the +internals mailing list, in which case an additional two-week period MUST pass +without objection or RFC request before the feature can be merged. + +Pull requests MAY be merged before the one-month period ends. However, if a +core developer raises an objection or requests an RFC after the merge but +within the one-month window, the feature MUST be reverted. See also `the voting RFC `_. @@ -291,8 +311,6 @@ We have voting plugin for dokuwiki (doodle2) that allows voting on the wiki The roles of the release managers are about being a facilitator: - Manage the release process -- Start the decisions discussions and vote about the features and change for a - given release - Create a roadmap and planing according to this RFC - Package the releases (test and final releases) - Decide which bug fixes can be applied to a release, within the cases defined @@ -302,10 +320,6 @@ But they are not: - Decide which features, extension or SAPI get in a release or not -Discussions or requests for a feature or to apply a given patch must be done on -the public internals mailing list or in the security mailing (ideally using the -bug tracker) - **************************** Release managers selection **************************** From b92c3c03a6e624c9750acebc23e8c7b5e9b5a06d Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Fri, 9 May 2025 13:29:53 +0200 Subject: [PATCH 02/22] Reword minor version changes (feedback from Tim) --- release-process.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/release-process.rst b/release-process.rst index 4dd4b17..b0865d7 100644 --- a/release-process.rst +++ b/release-process.rst @@ -52,12 +52,11 @@ Minor Version Number - Bugfixes - New features - Extensions support can be ended (moved to PECL) - - Backward compatibility must be preserved unless explicitly broken by an - approved RFC. - - API compatibility for user-facing code must be preserved unless an RFC - explicitly allows a breaking change. - - ABI and internal API compatibility may be broken if necessary, without - requiring an RFC. + - Syntaxt backward compatility MUST be preserved (every PHP program that + compiles must continue to compile) + - API backward compatibility breaks SHOULD be limited to extensions / the + API of functions within an extension + - ABI and internal API compatibility may be broken if necessary - Source compatibility should be kept if possible, while breakages are allowed From 9b9c4f29a6959be5fbbb98a9f4a0375ee2ea7944 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Fri, 9 May 2025 13:54:00 +0200 Subject: [PATCH 03/22] Define BC and fix typo --- release-process.rst | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/release-process.rst b/release-process.rst index b0865d7..08bb529 100644 --- a/release-process.rst +++ b/release-process.rst @@ -28,9 +28,30 @@ Roughly: No feature addition after final x.y.0 release (or x.0.0). -Backward compatibility MUST be respected within the same major release (e.g., -8.x.x). Binary compatibility (API or ABI) MAY be broken between two features -releases, f.e. between 8.3 and 8.4. + +Backward Compatibility +====================== + +A backward compatibility (BC) break is defined as any change that prevents +existing, valid, userland code from continuing to behave as it did in a +previous version within the same major release. + +The following are not considered BC breaks: + +- Adding deprecations. Code that triggers a deprecation warning continues to + work and is still valid. Converting deprecations into exceptions is a user + choice and not part of the language's default behavior. + +- Adding new symbols (e.g., functions, classes, constants), even if they may + conflict with user-defined names. While these additions can cause name + conflicts, they are not classified as BC breaks. RFCs and contributors + SHOULD make a best effort to minimize the risk of conflicts when choosing + new names, but SHOULD NOT pick significantly worse names purely to reduce + conflict risk. + +- Behavior changes in undefined or undocumented edge cases MAY be allowed if + well justified. However, care SHOULD be taken to minimize disruption. + Major Version Number ==================== @@ -52,7 +73,7 @@ Minor Version Number - Bugfixes - New features - Extensions support can be ended (moved to PECL) - - Syntaxt backward compatility MUST be preserved (every PHP program that + - Syntax backward compatibility MUST be preserved (every PHP program that compiles must continue to compile) - API backward compatibility breaks SHOULD be limited to extensions / the API of functions within an extension @@ -285,7 +306,9 @@ core developer (someone with commit access to php-src) raises an objection or requests an RFC within one month of the implementation pull request being opened. A core developer MAY also request that the feature be discussed on the internals mailing list, in which case an additional two-week period MUST pass -without objection or RFC request before the feature can be merged. +without objection or RFC request before the feature can be merged. However, +any change that breaks user-facing backward compatibility MUST go through the +RFC process. Pull requests MAY be merged before the one-month period ends. However, if a core developer raises an objection or requests an RFC after the merge but From b338ee2f1a1e1f08dddac94138384038081169fc Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Mon, 12 May 2025 11:51:51 +0200 Subject: [PATCH 04/22] Update formatting --- release-process.rst | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/release-process.rst b/release-process.rst index 08bb529..25e896f 100644 --- a/release-process.rst +++ b/release-process.rst @@ -28,13 +28,12 @@ Roughly: No feature addition after final x.y.0 release (or x.0.0). - Backward Compatibility ====================== A backward compatibility (BC) break is defined as any change that prevents -existing, valid, userland code from continuing to behave as it did in a -previous version within the same major release. +existing, valid, userland code from continuing to behave as it did in a previous +version within the same major release. The following are not considered BC breaks: @@ -44,15 +43,13 @@ The following are not considered BC breaks: - Adding new symbols (e.g., functions, classes, constants), even if they may conflict with user-defined names. While these additions can cause name - conflicts, they are not classified as BC breaks. RFCs and contributors - SHOULD make a best effort to minimize the risk of conflicts when choosing - new names, but SHOULD NOT pick significantly worse names purely to reduce - conflict risk. + conflicts, they are not classified as BC breaks. RFCs and contributors SHOULD + make a best effort to minimize the risk of conflicts when choosing new names, + but SHOULD NOT pick significantly worse names purely to reduce conflict risk. - Behavior changes in undefined or undocumented edge cases MAY be allowed if well justified. However, care SHOULD be taken to minimize disruption. - Major Version Number ==================== @@ -274,8 +271,8 @@ After the general availability release: profile regressions. - Regression fixes should be applied only exceptionally for small - regressions or regressions introduced by security fixes and it - should get RM approval. + regressions or regressions introduced by security fixes and it should + get RM approval. - Updates to ABI incompatible versions of dependent libraries on Windows are **not** performed. @@ -306,13 +303,13 @@ core developer (someone with commit access to php-src) raises an objection or requests an RFC within one month of the implementation pull request being opened. A core developer MAY also request that the feature be discussed on the internals mailing list, in which case an additional two-week period MUST pass -without objection or RFC request before the feature can be merged. However, -any change that breaks user-facing backward compatibility MUST go through the -RFC process. +without objection or RFC request before the feature can be merged. However, any +change that breaks user-facing backward compatibility MUST go through the RFC +process. -Pull requests MAY be merged before the one-month period ends. However, if a -core developer raises an objection or requests an RFC after the merge but -within the one-month window, the feature MUST be reverted. +Pull requests MAY be merged before the one-month period ends. However, if a core +developer raises an objection or requests an RFC after the merge but within the +one-month window, the feature MUST be reverted. See also `the voting RFC `_. From a706a8561db0174b6c2015a4229abb18149ddfb9 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 13 May 2025 11:36:40 +0200 Subject: [PATCH 05/22] Address feedback and properly use key words --- README.rst | 11 ++++++++ release-process.rst | 67 +++++++++++++++++++++++++-------------------- 2 files changed, 49 insertions(+), 29 deletions(-) diff --git a/README.rst b/README.rst index 4933507..4deb2b1 100644 --- a/README.rst +++ b/README.rst @@ -26,6 +26,17 @@ It contains the following items: - `Third-Party code `_: The circumstances under which the PHP project will use PHP code written by third parties in the ecosystem. +*********************** + Requirements Notation +*********************** + +The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL +NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"NOT +RECOMMENDED"**, **"MAY"**, and **"OPTIONAL"** in this document are to be +interpreted as described in `RFC 2119 +`_ when, and only when, they +appear in all capitals, as shown here. + ************ Formatting ************ diff --git a/release-process.rst b/release-process.rst index 25e896f..24ea178 100644 --- a/release-process.rst +++ b/release-process.rst @@ -10,6 +10,7 @@ :Updated by: https://wiki.php.net/rfc/release_cycle_update + https://wiki.php.net/rfc/policy-release-process-update This document outlines the release cycles of the PHP language. @@ -55,27 +56,34 @@ Major Version Number - x.y.z to x+1.0.0 - - Bug fixes - - New features - - Extensions support can be ended (moved to PECL) - - Backward compatibility can be broken - - API compatibility can be broken (internals and userland) - - ABI can be broken (internals) + - It SHALL included bugfixes and new features. + - Extensions support MAY be ended (moved to PECL) + - Backward compatibility MAY be broken + - API compatibility MAY be broken (internals and userland) + - ABI MAY be broken (internals) Minor Version Number ==================== - x.y.z to x.y+1.z - - Bugfixes - - New features - - Extensions support can be ended (moved to PECL) - - Syntax backward compatibility MUST be preserved (every PHP program that - compiles must continue to compile) - - API backward compatibility breaks SHOULD be limited to extensions / the + - It SHOULD included bugfixes and new features. + + - Extensions support MAY be ended (moved to PECL). + + - Syntax backward compatibility SHOULD be preserved (every PHP program that + compiles must continue to compile). + + - Backwards compatibility breaks in minor versions MUST NOT result in silent + behavioral differences. Instead any breaking change MUST be "obvious" when + executing the program. + + - API backward compatibility breaks SHOULD be limited to extensions, or the API of functions within an extension - - ABI and internal API compatibility may be broken if necessary - - Source compatibility should be kept if possible, while breakages are + + - ABI and internal API compatibility breaks are NOT RECOMMENDED. + + - Source compatibility SHOULD be kept if possible, while breakages are allowed Patch Version Number @@ -83,21 +91,22 @@ Patch Version Number - x.y.z to x.y.z+1 - - Bug fixes and security patches only - - Extensions support can't be removed (like move them to PECL) - - Backward compatibility must be kept (internals and userland) - - ABI and internal API compatibility must be preserved, except in the case - of HIGH severity security issues where no other option is possible. + - It SHOULD included bug fixes and security patches + - New features MUST NOT be added. + - Extensions support MUST NOT be removed (like move them to PECL) + - Backward compatibility MUST be kept (internals and userland) + - ABI and internal API compatibility SHOULD be preserved for high severity + security issues, and MUST be preserved for all other security issues. It is critical to understand the consequences of breaking BC, APIs or ABIs (only -internals related). It should not be done for the sake of doing it. RFCs +internals related). It SHOULD NOT be done for the sake of doing it. RFCs explaining the reasoning behind a breakage and the consequences along with test cases and patch(es) should help. -If a HIGH severity security fix requires breaking the internal ABI or API, a -proper migration path must be provided, and the impact should be minimized as -much as possible. This should also be accompanied by additional communication -during the release. +If a high severity security fix requires breaking the internal ABI or API, a +proper migration path MUST be provided, and the impact MUST be minimized as much +as possible. This MUST also be accompanied by additional communication during +the release. See the following links for explanation about API and ABI: @@ -254,7 +263,7 @@ After the general availability release: - Release only when there is a security issue or regression issue to address. - - Security fix, compatibility build fix and regression fix releases + - Security fix, compatibility build fix, and regression fix releases SHOULD occur on the same date as bug fix releases for the other branches. Exceptions can be made for high risk security issues or high profile regressions. @@ -265,14 +274,14 @@ After the general availability release: - Release only when there is a security issue. - - Security fix, compatibility build fix and regression fix releases + - Security fix, compatibility build fix, and regression fix releases SHOULD occur on the same date as bug fix releases for the other branches. Exceptions can be made for high risk security issues or high profile regressions. - - Regression fixes should be applied only exceptionally for small - regressions or regressions introduced by security fixes and it should - get RM approval. + - Regression fixes SHOULD be applied only exceptionally for small + regressions or regressions introduced by security fixes. The regression + fixes MUST get RM approval. - Updates to ABI incompatible versions of dependent libraries on Windows are **not** performed. From 20dc00d431ee591b2b10221be44fbd75806ec739 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 13 May 2025 13:49:38 +0200 Subject: [PATCH 06/22] Update syntaxt backward compatiblity note --- release-process.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/release-process.rst b/release-process.rst index 24ea178..0ec3032 100644 --- a/release-process.rst +++ b/release-process.rst @@ -71,8 +71,8 @@ Minor Version Number - Extensions support MAY be ended (moved to PECL). - - Syntax backward compatibility SHOULD be preserved (every PHP program that - compiles must continue to compile). + - Syntax backward compatibility SHOULD be preserved - every PHP program that + compiles SHOULD continue to compile. - Backwards compatibility breaks in minor versions MUST NOT result in silent behavioral differences. Instead any breaking change MUST be "obvious" when @@ -310,11 +310,12 @@ Internal API changes (those that do not affect the user-facing API), as well as user-facing features in extensions and SAPIs, do not require an RFC unless a core developer (someone with commit access to php-src) raises an objection or requests an RFC within one month of the implementation pull request being -opened. A core developer MAY also request that the feature be discussed on the -internals mailing list, in which case an additional two-week period MUST pass -without objection or RFC request before the feature can be merged. However, any -change that breaks user-facing backward compatibility MUST go through the RFC -process. +opened. + +A core developer MAY also request that the feature be discussed on the internals +mailing list, in which case an additional two-week period MUST pass without +objection or RFC request before the feature can be merged. However, any change +that breaks user-facing backward compatibility MUST go through the RFC process. Pull requests MAY be merged before the one-month period ends. However, if a core developer raises an objection or requests an RFC after the merge but within the From c897ed7ceb080cf55767777b2c438decad8c1617 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 13 May 2025 16:56:43 +0200 Subject: [PATCH 07/22] Add note about UPGRADING and extend symbol rule --- release-process.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/release-process.rst b/release-process.rst index 0ec3032..2bb7dec 100644 --- a/release-process.rst +++ b/release-process.rst @@ -10,6 +10,8 @@ :Updated by: https://wiki.php.net/rfc/release_cycle_update + +:Updated by: https://wiki.php.net/rfc/policy-release-process-update This document outlines the release cycles of the PHP language. @@ -42,11 +44,12 @@ The following are not considered BC breaks: work and is still valid. Converting deprecations into exceptions is a user choice and not part of the language's default behavior. -- Adding new symbols (e.g., functions, classes, constants), even if they may - conflict with user-defined names. While these additions can cause name - conflicts, they are not classified as BC breaks. RFCs and contributors SHOULD - make a best effort to minimize the risk of conflicts when choosing new names, - but SHOULD NOT pick significantly worse names purely to reduce conflict risk. +- Adding new symbols (e.g., functions, classes, constants) into the global or + core extension namespace, even if they may conflict with user-defined names. + While these additions can cause name conflicts, they are not classified as BC + breaks. RFCs and contributors SHOULD make a best effort to minimize the risk + of conflicts when choosing new names, but SHOULD NOT pick significantly worse + names purely to reduce conflict risk. - Behavior changes in undefined or undocumented edge cases MAY be allowed if well justified. However, care SHOULD be taken to minimize disruption. @@ -108,6 +111,11 @@ proper migration path MUST be provided, and the impact MUST be minimized as much as possible. This MUST also be accompanied by additional communication during the release. +All new user-facing features MUST be mentioned in the `UPGRADING +`_ document. All API and +ABI breaks MUST be mentioned in the `UPGRADING.INTERNALS +`_ document. + See the following links for explanation about API and ABI: - http://en.wikipedia.org/wiki/Application_programming_interface From 5a4bdb7a5d518665bf806cdf3f7455025d892ea4 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 13 May 2025 18:30:37 +0200 Subject: [PATCH 08/22] Move notation from coding standard and update updated by --- README.rst | 11 ++++++----- coding-standards-and-naming.rst | 8 -------- release-process.rst | 14 ++++++++------ 3 files changed, 14 insertions(+), 19 deletions(-) diff --git a/README.rst b/README.rst index 4deb2b1..46fe144 100644 --- a/README.rst +++ b/README.rst @@ -30,11 +30,12 @@ It contains the following items: Requirements Notation *********************** -The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL -NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"NOT -RECOMMENDED"**, **"MAY"**, and **"OPTIONAL"** in this document are to be -interpreted as described in `RFC 2119 -`_ when, and only when, they +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in `BCP 14 +`_ [`RFC2119 +`_] [`RFC8174 +`_] when, and only when, they appear in all capitals, as shown here. ************ diff --git a/coding-standards-and-naming.rst b/coding-standards-and-naming.rst index 15f67c6..2e8d704 100644 --- a/coding-standards-and-naming.rst +++ b/coding-standards-and-naming.rst @@ -2,14 +2,6 @@ Coding Standards and Naming Policy #################################### -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this -document are to be interpreted as described in `BCP 14 -`_ [`RFC2119 -`_] [`RFC8174 -`_] when, and only when, they -appear in all capitals, as shown here. - This policy lists standards that any programmer adding or changing code in PHP should follow. diff --git a/release-process.rst b/release-process.rst index 2bb7dec..800053d 100644 --- a/release-process.rst +++ b/release-process.rst @@ -5,14 +5,16 @@ .. contents:: :depth: 2 -:From: - https://wiki.php.net/rfc/releaseprocess +**From:** -:Updated by: - https://wiki.php.net/rfc/release_cycle_update +- `Request for Comments: Release Process + `_ -:Updated by: - https://wiki.php.net/rfc/policy-release-process-update +**Updated by:** + +- `RFC: Release Cycle Update `_ +- `RFC: Policy Release Process Update + `_ This document outlines the release cycles of the PHP language. From 20445c7037519dc3d1fdb2aea5fad3173806bcfe Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 13 May 2025 18:37:08 +0200 Subject: [PATCH 09/22] Move source to note --- release-process.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/release-process.rst b/release-process.rst index 800053d..0c711a1 100644 --- a/release-process.rst +++ b/release-process.rst @@ -5,16 +5,15 @@ .. contents:: :depth: 2 -**From:** +.. note:: -- `Request for Comments: Release Process - `_ + **From:** + - `RFC: Release Process `_ -**Updated by:** + **Updated by:** + - `RFC: Release Cycle Update `_ + - `RFC: Policy Release Process Update `_ -- `RFC: Release Cycle Update `_ -- `RFC: Policy Release Process Update - `_ This document outlines the release cycles of the PHP language. From 5510a618c892252a4033526b41a44ed8c68d9ae8 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 13 May 2025 18:43:47 +0200 Subject: [PATCH 10/22] Usa table for sources --- release-process.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/release-process.rst b/release-process.rst index 0c711a1..9c05a80 100644 --- a/release-process.rst +++ b/release-process.rst @@ -5,15 +5,17 @@ .. contents:: :depth: 2 -.. note:: - - **From:** - - `RFC: Release Process `_ - - **Updated by:** - - `RFC: Release Cycle Update `_ - - `RFC: Policy Release Process Update `_ - +**Sources:** + ++------------------+--------------------------------------------------------------+ +| Original RFC | `Request for Comments: Release Process | +| | `_ | ++------------------+--------------------------------------------------------------+ +| Updates | - `RFC: Release Cycle Update | +| | `_ | +| | - `RFC: Policy Release Process Update | +| | `_ | ++------------------+--------------------------------------------------------------+ This document outlines the release cycles of the PHP language. From 22cabf3218f38e072e1f3874b2680cdab71f5772 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 13 May 2025 18:46:57 +0200 Subject: [PATCH 11/22] Update table formatting --- release-process.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/release-process.rst b/release-process.rst index 9c05a80..62f68f7 100644 --- a/release-process.rst +++ b/release-process.rst @@ -7,15 +7,15 @@ **Sources:** -+------------------+--------------------------------------------------------------+ -| Original RFC | `Request for Comments: Release Process | -| | `_ | -+------------------+--------------------------------------------------------------+ -| Updates | - `RFC: Release Cycle Update | -| | `_ | -| | - `RFC: Policy Release Process Update | -| | `_ | -+------------------+--------------------------------------------------------------+ ++--------------+---------------------------------------------------------------+ +| Original RFC | `Request for Comments: Release Process | +| | `_ | ++--------------+---------------------------------------------------------------+ +| Updates | - `RFC: Release Cycle Update | +| | `_ | +| | - `RFC: Policy Release Process Update | +| | `_ | ++--------------+---------------------------------------------------------------+ This document outlines the release cycles of the PHP language. From dfa7a39d522fa333a5634bca15cc2b40c9ddc365 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 13 May 2025 18:49:36 +0200 Subject: [PATCH 12/22] Fix formatting a bit more --- release-process.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/release-process.rst b/release-process.rst index 62f68f7..9d55c0c 100644 --- a/release-process.rst +++ b/release-process.rst @@ -5,11 +5,11 @@ .. contents:: :depth: 2 -**Sources:** +Sources +--------------+---------------------------------------------------------------+ -| Original RFC | `Request for Comments: Release Process | -| | `_ | +| Original RFC | - `Request for Comments: Release Process | +| | `_ | +--------------+---------------------------------------------------------------+ | Updates | - `RFC: Release Cycle Update | | | `_ | From 6eda868a64270f2a5fb7167753ce3155abccb956 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 13 May 2025 18:50:29 +0200 Subject: [PATCH 13/22] Fix table formatting --- release-process.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/release-process.rst b/release-process.rst index 9d55c0c..a51cd0a 100644 --- a/release-process.rst +++ b/release-process.rst @@ -8,8 +8,8 @@ Sources +--------------+---------------------------------------------------------------+ -| Original RFC | - `Request for Comments: Release Process | -| | `_ | +| Original RFC | - `Request for Comments: Release Process | +| | `_ | +--------------+---------------------------------------------------------------+ | Updates | - `RFC: Release Cycle Update | | | `_ | From e54b88b0324aefbc571bef7a6a96e64b607a90d3 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 27 May 2025 11:11:03 +0200 Subject: [PATCH 14/22] Address feedback from Ilija and Jorg --- release-process.rst | 96 +++++++++++++++++++++++++++++---------------- 1 file changed, 62 insertions(+), 34 deletions(-) diff --git a/release-process.rst b/release-process.rst index a51cd0a..64107b1 100644 --- a/release-process.rst +++ b/release-process.rst @@ -41,7 +41,32 @@ A backward compatibility (BC) break is defined as any change that prevents existing, valid, userland code from continuing to behave as it did in a previous version within the same major release. -The following are not considered BC breaks: +Compatibility Terminology +------------------------- + +- **Syntax Compatibility**: Ensures that valid PHP code from an earlier version + continues to parse and compile without syntax errors in the newer version. + +- **Userland API Compatibility**: Refers to the consistency of functions, + classes, constants, and other interfaces exposed to userland PHP code. + Breaking this means public APIs behave differently or are removed. + +- **Internal API Compatibility**: The source-level interface between PHP core, + extensions, and SAPIs. It is relevant at **compile time** — extensions that + use the internal API may fail to compile if it changes. Maintainers need to + update and recompile extensions when internal APIs change. + +- **ABI (Application Binary Interface) Compatibility**: The binary-level + interface between the compiled PHP core and compiled extensions. It is + relevant at **run time** — changes may cause extensions to crash, misbehave, + or fail to load if they were compiled against an older version. ABI stability + ensures that precompiled extensions continue to work across patch releases + without recompilation. + +BC Breaks and Exceptions +------------------------ + +The following are **not considered** BC breaks: - Adding deprecations. Code that triggers a deprecation warning continues to work and is still valid. Converting deprecations into exceptions is a user @@ -57,73 +82,76 @@ The following are not considered BC breaks: - Behavior changes in undefined or undocumented edge cases MAY be allowed if well justified. However, care SHOULD be taken to minimize disruption. +On Breaking Compatibility +------------------------- + +Breaking BC, APIs, or ABIs (internal) SHOULD NOT be done lightly or for the sake +of doing it. RFCs explaining the reasoning behind a breakage MUST include: + +- Clear justification for the change +- A summary of its consequences +- Migration guidance +- Test cases and patches + +If a high severity security fix requires breaking the internal ABI or API, a +proper migration path MUST be provided, and the impact MUST be minimized as much +as possible. This MUST also be accompanied by additional communication during +the release. + +All new user-facing features MUST be mentioned in the `UPGRADING +`_ document. + +All API and ABI breaks MUST be mentioned in the `UPGRADING.INTERNALS +`_ document. + +Further reading: + +- http://en.wikipedia.org/wiki/Application_programming_interface +- http://en.wikipedia.org/wiki/Application_binary_interface + Major Version Number ==================== - x.y.z to x+1.0.0 - - It SHALL included bugfixes and new features. + - It SHALL include bugfixes and new features. - Extensions support MAY be ended (moved to PECL) - Backward compatibility MAY be broken - - API compatibility MAY be broken (internals and userland) - - ABI MAY be broken (internals) Minor Version Number ==================== -- x.y.z to x.y+1.z +- x.y.z to x.y+1.0 - - It SHOULD included bugfixes and new features. + - It SHOULD include bugfixes and new features. - Extensions support MAY be ended (moved to PECL). - Syntax backward compatibility SHOULD be preserved - every PHP program that compiles SHOULD continue to compile. - - Backwards compatibility breaks in minor versions MUST NOT result in silent + - Backward compatibility breaks in minor versions MUST NOT result in silent behavioral differences. Instead any breaking change MUST be "obvious" when - executing the program. + executing the program. It means it SHOULD either throw exception or + trigger error. - - API backward compatibility breaks SHOULD be limited to extensions, or the - API of functions within an extension + - Userland API backward compatibility breaks SHOULD be limited to + extensions, or the API of functions within an extension. - ABI and internal API compatibility breaks are NOT RECOMMENDED. - - Source compatibility SHOULD be kept if possible, while breakages are - allowed - Patch Version Number ==================== - x.y.z to x.y.z+1 - - It SHOULD included bug fixes and security patches + - It SHOULD include bug fixes and security patches - New features MUST NOT be added. - Extensions support MUST NOT be removed (like move them to PECL) - Backward compatibility MUST be kept (internals and userland) - ABI and internal API compatibility SHOULD be preserved for high severity security issues, and MUST be preserved for all other security issues. -It is critical to understand the consequences of breaking BC, APIs or ABIs (only -internals related). It SHOULD NOT be done for the sake of doing it. RFCs -explaining the reasoning behind a breakage and the consequences along with test -cases and patch(es) should help. - -If a high severity security fix requires breaking the internal ABI or API, a -proper migration path MUST be provided, and the impact MUST be minimized as much -as possible. This MUST also be accompanied by additional communication during -the release. - -All new user-facing features MUST be mentioned in the `UPGRADING -`_ document. All API and -ABI breaks MUST be mentioned in the `UPGRADING.INTERNALS -`_ document. - -See the following links for explanation about API and ABI: - -- http://en.wikipedia.org/wiki/Application_programming_interface -- http://en.wikipedia.org/wiki/Application_binary_interface - Example time line with only one major version at a time ------------------------------------------------------- From 2ab125c17f9c54e0675699f1b5bad43f56792a12 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 27 May 2025 11:21:47 +0200 Subject: [PATCH 15/22] Update major version list --- release-process.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/release-process.rst b/release-process.rst index 64107b1..a285dbd 100644 --- a/release-process.rst +++ b/release-process.rst @@ -115,8 +115,10 @@ Major Version Number - x.y.z to x+1.0.0 - It SHALL include bugfixes and new features. - - Extensions support MAY be ended (moved to PECL) - - Backward compatibility MAY be broken + - Extensions support MAY be ended (moved to PECL). + - Userland API backward compatibility MAY be broken. + - Internal API backward compatibility MAY be broken. + - ABI backward compatibility MAY be broken. Minor Version Number ==================== @@ -138,7 +140,9 @@ Minor Version Number - Userland API backward compatibility breaks SHOULD be limited to extensions, or the API of functions within an extension. - - ABI and internal API compatibility breaks are NOT RECOMMENDED. + - Internal API compatibility breaks are NOT RECOMMENDED. + + - ABI backward compatibility MAY be broken. Patch Version Number ==================== From 7907392ef2cafc153d3d15af36d46278f49cbd42 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 10 Jun 2025 11:33:08 +0200 Subject: [PATCH 16/22] Add notes about SAPI support and removal --- release-process.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/release-process.rst b/release-process.rst index a285dbd..f96cfa3 100644 --- a/release-process.rst +++ b/release-process.rst @@ -98,6 +98,11 @@ proper migration path MUST be provided, and the impact MUST be minimized as much as possible. This MUST also be accompanied by additional communication during the release. +SAPI removal SHOULD generally occur only in a major version. However, in +exceptional cases where a SAPI presents significant maintenance or security +concerns, an exception MAY be made. In all cases, the removal MUST go through +the RFC process. + All new user-facing features MUST be mentioned in the `UPGRADING `_ document. @@ -116,6 +121,7 @@ Major Version Number - It SHALL include bugfixes and new features. - Extensions support MAY be ended (moved to PECL). + - SAPI support MAY be ended (removed from the php-src repository). - Userland API backward compatibility MAY be broken. - Internal API backward compatibility MAY be broken. - ABI backward compatibility MAY be broken. @@ -129,6 +135,8 @@ Minor Version Number - Extensions support MAY be ended (moved to PECL). + - SAPI support is RECOMMENDED to be kept. + - Syntax backward compatibility SHOULD be preserved - every PHP program that compiles SHOULD continue to compile. From a6cd5320fa1cf5c8bee404ea8e2e0dc3942aee3b Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 24 Jun 2025 15:01:15 +0200 Subject: [PATCH 17/22] Extend recommendations for minor version breaks --- release-process.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/release-process.rst b/release-process.rst index f96cfa3..0a1b445 100644 --- a/release-process.rst +++ b/release-process.rst @@ -140,10 +140,15 @@ Minor Version Number - Syntax backward compatibility SHOULD be preserved - every PHP program that compiles SHOULD continue to compile. - - Backward compatibility breaks in minor versions MUST NOT result in silent - behavioral differences. Instead any breaking change MUST be "obvious" when - executing the program. It means it SHOULD either throw exception or - trigger error. + - Backward compatibility breaks in minor versions SHOULD NOT result in + silent behavioral differences. Instead any breaking change SHOULD be + "obvious" when executing the program. It means it SHOULD either throw + exception or trigger error. + + - Backward compatibility breaks introduced in minor versions SHOULD allow + for straightforward code adjustments to maintain compatibility with both + the current and upcoming PHP versions. Such adjustments SHOULD be feasible + with basic tooling and not require complex static analysis. - Userland API backward compatibility breaks SHOULD be limited to extensions, or the API of functions within an extension. From d9acb5199502f37fc53487e638a528d629fb62aa Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 24 Jun 2025 15:09:10 +0200 Subject: [PATCH 18/22] Use "these documents" in README --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 46fe144..7040221 100644 --- a/README.rst +++ b/README.rst @@ -31,8 +31,8 @@ It contains the following items: *********************** The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this -document are to be interpreted as described in `BCP 14 +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in these +documents are to be interpreted as described in `BCP 14 `_ [`RFC2119 `_] [`RFC8174 `_] when, and only when, they From 1bc0718418df9eef87474b91a7046eeb1126f625 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Wed, 16 Jul 2025 15:28:30 +0200 Subject: [PATCH 19/22] Add minor changes to the rules to address latest comments --- release-process.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/release-process.rst b/release-process.rst index 0a1b445..330e6fe 100644 --- a/release-process.rst +++ b/release-process.rst @@ -119,12 +119,14 @@ Major Version Number - x.y.z to x+1.0.0 - - It SHALL include bugfixes and new features. + - It SHOULD include bugfixes and new features. - Extensions support MAY be ended (moved to PECL). - SAPI support MAY be ended (removed from the php-src repository). - - Userland API backward compatibility MAY be broken. - - Internal API backward compatibility MAY be broken. - ABI backward compatibility MAY be broken. + - Internal API backward compatibility MAY be broken. + - Userland API backward compatibility MAY be broken. + - The significant userland API backward compatibility breaks SHOULD be + preceded by the deprecation phase in the previous major version. Minor Version Number ==================== @@ -137,6 +139,10 @@ Minor Version Number - SAPI support is RECOMMENDED to be kept. + - Internal API compatibility breaks are NOT RECOMMENDED. + + - ABI backward compatibility MAY be broken. + - Syntax backward compatibility SHOULD be preserved - every PHP program that compiles SHOULD continue to compile. @@ -150,12 +156,6 @@ Minor Version Number the current and upcoming PHP versions. Such adjustments SHOULD be feasible with basic tooling and not require complex static analysis. - - Userland API backward compatibility breaks SHOULD be limited to - extensions, or the API of functions within an extension. - - - Internal API compatibility breaks are NOT RECOMMENDED. - - - ABI backward compatibility MAY be broken. Patch Version Number ==================== From 401fde1459fe5295715300592a909b6bf9b85314 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Wed, 16 Jul 2025 15:31:01 +0200 Subject: [PATCH 20/22] Fix CS --- release-process.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/release-process.rst b/release-process.rst index 330e6fe..f8893ad 100644 --- a/release-process.rst +++ b/release-process.rst @@ -156,7 +156,6 @@ Minor Version Number the current and upcoming PHP versions. Such adjustments SHOULD be feasible with basic tooling and not require complex static analysis. - Patch Version Number ==================== From a8512e7c28c3552095154765a814db9871616c79 Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Wed, 16 Jul 2025 15:38:54 +0200 Subject: [PATCH 21/22] Remove superfluous the --- release-process.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/release-process.rst b/release-process.rst index f8893ad..df85fab 100644 --- a/release-process.rst +++ b/release-process.rst @@ -125,8 +125,8 @@ Major Version Number - ABI backward compatibility MAY be broken. - Internal API backward compatibility MAY be broken. - Userland API backward compatibility MAY be broken. - - The significant userland API backward compatibility breaks SHOULD be - preceded by the deprecation phase in the previous major version. + - Significant userland API backward compatibility breaks SHOULD be preceded + by the deprecation phase in the previous major version. Minor Version Number ==================== From 97833c8a412fc91b9c4aaa900b57139f6450c2fa Mon Sep 17 00:00:00 2001 From: Jakub Zelenka Date: Tue, 22 Jul 2025 23:18:18 +0200 Subject: [PATCH 22/22] Update rules for security branches fixes --- release-process.rst | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/release-process.rst b/release-process.rst index df85fab..7cc9fde 100644 --- a/release-process.rst +++ b/release-process.rst @@ -310,8 +310,12 @@ After the general availability release: - Until the end of year 3 (e.g., for PHP 8.4: until Dec 31, 2027): - - Security fixes, and fixes to address regressions introduced during a - normal bug fix release. + - Security fixes, compatibility fixes, fixes to address regressions + introduced during a normal bug fix release, and fixes for crashes like + use after free or segmentation faults. + + - Fixes for crashes SHOULD be applied only exceptionally for small fixes. + The fix MUST get RM approval. - Updates to ABI incompatible versions of dependent libraries on Windows. @@ -325,22 +329,24 @@ After the general availability release: - Until the end of year 4 (e.g., for PHP 8.4: until Dec 31, 2028): - - Security fixes **only**. + - Security fixes, compatibility build fixes, fixes to address regressions + caused by a security fix, and fixes for crashes like use after free or + segmentation faults. + + - Regression fixes and fixes for crashes SHOULD be applied only + exceptionally for small fixes. The fix MUST get RM approval. - - Release only when there is a security issue. + - Updates to ABI incompatible versions of dependent libraries on Windows + are **not** performed. + + - Release only when there is a security issue or regression issue to + address. - Security fix, compatibility build fix, and regression fix releases SHOULD occur on the same date as bug fix releases for the other branches. Exceptions can be made for high risk security issues or high profile regressions. - - Regression fixes SHOULD be applied only exceptionally for small - regressions or regressions introduced by security fixes. The regression - fixes MUST get RM approval. - - - Updates to ABI incompatible versions of dependent libraries on Windows - are **not** performed. - *"End of year" means:* The end of the calendar year, i.e., Dec 31 at 24:00 UTC. The numbered years in the examples (e.g., "end of year 2") indicate the number of calendar years following the *original planned GA release date*. For example,