Skip to content

Add changes to the release process #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 16 commits into
base: main
Choose a base branch
from
Open

Add changes to the release process #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
5e4a08c
Add changes to the release process
bukka May 9, 2025
b92c3c0
Reword minor version changes (feedback from Tim)
bukka May 9, 2025
9b9c4f2
Define BC and fix typo
bukka May 9, 2025
b338ee2
Update formatting
bukka May 12, 2025
a706a85
Address feedback and properly use key words
bukka May 13, 2025
20dc00d
Update syntaxt backward compatiblity note
bukka May 13, 2025
c897ed7
Add note about UPGRADING and extend symbol rule
bukka May 13, 2025
5a4bdb7
Move notation from coding standard and update updated by
bukka May 13, 2025
20445c7
Move source to note
bukka May 13, 2025
5510a61
Usa table for sources
bukka May 13, 2025
22cabf3
Update table formatting
bukka May 13, 2025
dfa7a39
Fix formatting a bit more
bukka May 13, 2025
6eda868
Fix table formatting
bukka May 13, 2025
e54b88b
Address feedback from Ilija and Jorg
bukka May 27, 2025
2ab125c
Update major version list
bukka May 27, 2025
7907392
Add notes about SAPI support and removal
bukka Jun 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,18 @@ It contains the following items:
- `Third-Party code <third-party-code.rst>`_: 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 `BCP 14
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this document, or in these documents? Not a real problem, but we ought to fix that.

<https://www.rfc-editor.org/bcp/bcp14.txt>`_ [`RFC2119
<https://datatracker.ietf.org/doc/html/rfc2119>`_] [`RFC8174
<https://datatracker.ietf.org/doc/html/rfc8174>`_] when, and only when, they
appear in all capitals, as shown here.

************
Formatting
************
Expand Down
8 changes: 0 additions & 8 deletions coding-standards-and-naming.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<https://www.rfc-editor.org/bcp/bcp14.txt>`_ [`RFC2119
<https://datatracker.ietf.org/doc/html/rfc2119>`_] [`RFC8174
<https://datatracker.ietf.org/doc/html/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.

Expand Down
218 changes: 156 additions & 62 deletions release-process.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,17 @@
.. contents::
:depth: 2

:From:
https://wiki.php.net/rfc/releaseprocess

:Updated by:
https://wiki.php.net/rfc/release_cycle_update
Sources

+--------------+---------------------------------------------------------------+
| Original RFC | - `Request for Comments: Release Process |
| | <https://wiki.php.net/rfc/releaseprocess>`_ |
+--------------+---------------------------------------------------------------+
| Updates | - `RFC: Release Cycle Update |
| | <https://wiki.php.net/rfc/release_cycle_update>`_ |
| | - `RFC: Policy Release Process Update |
| | <https://wiki.php.net/rfc/policy-release-process-update>`_ |
+--------------+---------------------------------------------------------------+
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we not use list-table? changes to formatted tables become very noisy.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't seem to allow cell formatting (I need multiple lines for Updates)... But if you can put working nicer format, I'm happy to change it. I spent already quite a bit of time to get it to some acceptable state as it this sort of formatting quite suck in RST.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would just have done this:

*Original RFC:* `Request for Comments: Release Process <https://wiki.php.net/rfc/releaseprocess>`_

*Updated By:*

- `RFC: Release Cycle Update <https://wiki.php.net/rfc/release_cycle_update>`_
- `RFC: Policy Release Process Update <https://wiki.php.net/rfc/policy-release-process-update>`_

It doesn't have to be complicated.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried and it looks ugly.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See https://github.com/php/policies/blob/5a4bdb7a5d518665bf806cdf3f7455025d892ea4/release-process.rst . Basically it looks like it's part of the content.


This document outlines the release cycles of the PHP language.

Expand All @@ -28,55 +34,135 @@ 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.

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
choice and not part of the language's default behavior.

- 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.

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.

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
<https://github.com/php/php-src/blob/master/UPGRADING>`_ document.

All API and ABI breaks MUST be mentioned in the `UPGRADING.INTERNALS
<https://github.com/php/php-src/blob/master/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

- 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 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.

Minor Version Number
====================

- x.y.z to x.y+1.z
- x.y.z to x.y+1.0

- 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)
- Source compatibility should be kept if possible, while breakages are
allowed
- It SHOULD include bugfixes and new features.

Patch Version Number
====================
- Extensions support MAY be ended (moved to PECL).

- x.y.z to x.y.z+1
- SAPI support is RECOMMENDED to be kept.

- 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)
- Syntax backward compatibility SHOULD be preserved - every PHP program that
compiles SHOULD continue to compile.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given this is a SHOULD, I would find it useful to spell out when it is ok to violate this guideline. Namely, any breaking change should go through the RFC process. It should ultimately be up to the community to decide what BC breaks are acceptable. (I see this is later clarified).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already explicitly noted in Feature selection and development section:

However, any change that breaks user-facing backward compatibility MUST go through the RFC process.


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.
- 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.

See the following links for explanation about API and ABI:
- Userland API backward compatibility breaks SHOULD be limited to
extensions, or the API of functions within an extension.
Comment on lines +140 to +149
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to see something about “BC breaks must be simple to work-around in a cross-version way”, e.g. what I mentioned in https://externals.io/message/127328#127335.


- http://en.wikipedia.org/wiki/Application_programming_interface
- http://en.wikipedia.org/wiki/Application_binary_interface
- Internal API compatibility breaks are NOT RECOMMENDED.

- ABI backward compatibility MAY be broken.

Patch Version Number
====================

- x.y.z to x.y.z+1

- 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.

Example time line with only one major version at a time
-------------------------------------------------------
Expand Down Expand Up @@ -228,19 +314,25 @@ 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):

- Security fixes **only**.

- 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. The regression
fixes MUST get RM approval.

- Updates to ABI incompatible versions of dependent libraries on Windows
are **not** performed.
Expand All @@ -256,21 +348,29 @@ 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.

New features MUST be implemented and proposed using a GitHub pull request.

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.
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.

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.
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
one-month window, the feature MUST be reverted.

See also `the voting RFC <https://wiki.php.net/rfc/voting>`_.

Expand All @@ -291,8 +391,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
Expand All @@ -302,10 +400,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
****************************
Expand Down