Skip to content

release-process: update based on 8.5.0RC1 and discussions #19939

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
DanielEScherzer wants to merge 6 commits into
base: master
Choose a base branch
from
+61 −21
Open

release-process: update based on 8.5.0RC1 and discussions #19939

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ed61934
release-process: update based on 8.5.0RC1 and discussions
DanielEScherzer Sep 23, 2025
ea82281
.github/nightly_matrix.php needs to be updated
DanielEScherzer Sep 24, 2025
386670f
Also update push workflow; versions updated at last RC
DanielEScherzer Oct 21, 2025
75a450b
beta is from master
DanielEScherzer Oct 21, 2025
2aa1374
more branch instructions
DanielEScherzer Oct 21, 2025
f9184b6
fix stray letter
DanielEScherzer Oct 21, 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
82 changes: 61 additions & 21 deletions docs/release-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ repository available according to the release schedule.
The release schedule for each version is published on the
[PHP wiki](https://wiki.php.net):

- [PHP 8.5](https://wiki.php.net/todo/php85)
- [PHP 8.4](https://wiki.php.net/todo/php84)
- [PHP 8.3](https://wiki.php.net/todo/php83)
- [PHP 8.2](https://wiki.php.net/todo/php82)
Expand Down Expand Up @@ -137,14 +138,23 @@ slightly different steps. We'll call attention where the steps differ.
> During the first RC release, you will create (and push!) the version
> branch for the pre-GA release, e.g., `PHP-8.2`. See
> "[Forking a new version branch](#forking-a-new-version-branch)" below.
> From this point forward, all pre-GA release branches will be created from
> For the last RC release, and the subsequent GA release, follow the post-GA
> procedure, but until that point, pre-GA release branches will be created from
> this version branch. Again, these release branches are local-only. Do not
> push them!
>
> ```shell
> git checkout -b php-X.Y.0beta2-local-release-branch upstream/PHP-X.Y
> git checkout -b php-X.Y.0RC3-local-release-branch upstream/PHP-X.Y
> ```

> 💬 **Hint** \
> The *patch-level version branch* for GA (PHP X.Y.0) is created as part of the
> last *planned* RC release (currently PHP X.Y.0RC4). After the last RC is released
> additional bug fixes in the branch will not be a part of PHP X.Y.0. If a regression
Copy link
Member

@edorian edorian Oct 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

In the branch

referring to 8.5 not the 8.5.0 mentioned from above. Maybe clarify?

> is found that warrants including a fix in PHP X.Y.0, use the same process as
> for other patch releases - merge the patch as normal to PHP X.Y, and then cherry-pick
> the patch to the patch-level PHP X.Y.0 branch.

> 🔷 **Non-stable version branches: post-GA** \
> After GA, you will create (and push) a new *patch-level version branch*
> along with each non-stable release. For example, if you are building a
Expand Down Expand Up @@ -263,7 +273,7 @@ slightly different steps. We'll call attention where the steps differ.
The NEWS is updated at the *start* of the cycle for the next tag, e.g.
[Update NEWS for PHP 8.2.0 alpha2][] was sent as part of tagging 8.2.0 alpha **1**.

🔷 **For post-GA releases only,** switch back to the *version branch* for
🔷 **For post-GA releases, and the final pre-GA RC** switch back to the *version branch* for
your release (e.g., `PHP-8.2`) and bump the version numbers in
`main/php_version.h`, `Zend/zend.h`, `configure.ac` and `NEWS`. This prepares
the version branch for the next version.
Expand Down Expand Up @@ -291,11 +301,16 @@ slightly different steps. We'll call attention where the steps differ.
> Only release tags should have version numbers in these files that do not
> end in `-dev` (e.g., `8.1.7`, `8.1.7RC1`, `8.2.0alpha1`, etc.).

10. Push the changes to the `php-src`.
Do not forget to merge up PHP-X.Y all the way to master. When resolving
the conflicts, ignore the changes from PHP-X.Y in higher branches. It
means using something like `git checkout --ours .` when on PHP.X.Y+1 or
master after the merge resulting in the conflicts.
Copy link
Member

@edorian edorian Nov 4, 2025

Choose a reason for hiding this comment

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

Maybe this could use an example and maybe a reminder to set up merge.NEWS from https://wiki.php.net/vcs/gitfaq ?


11. Push the changes to the `php-src`.

```shell
git push upstream php-X.Y.ZRCn # tag name
git push upstream PHP-X.Y.Z # patch-level version branch (post-GA only)
git push upstream PHP-X.Y.Z # patch-level version branch (beginning with the last RC before GA)
git push upstream PHP-X.Y # version branch (post-branch creation only)
git push upstream master # version branch (pre-branch creation only)
```
Expand All @@ -306,28 +321,23 @@ slightly different steps. We'll call attention where the steps differ.
>
> Local-only release branches should not be pushed!

Do not forget to merge up PHP-X.Y all the way to master. When resolving
the conflicts, ignore the changes from PHP-X.Y in higher branches. It
means using something like `git checkout --ours .` when on PHP.X.Y+1 or
master after the merge resulting in the conflicts.

11. Run the following using the release tag to export the tree, create the
12. Run the following using the release tag to export the tree, create the
`configure` script, and build and compress three tarballs (`.tar.gz`,
`.tar.bz2` and `.tar.xz`).

```shell
./scripts/dev/makedist php-X.Y.ZRCn
```

12. Run the following using the release tag and your GPG key ID to sign the
13. Run the following using the release tag and your GPG key ID to sign the
tarballs and save the signatures to `php-X.Y.ZRCn.manifest`, which you can
upload to GitHub and include in the announcement emails.

```shell
./scripts/dev/gen_verify_stub X.Y.ZRCn YOURKEYID > php-X.Y.ZRCn.manifest
```

13. If you have the [GitHub command line tool][] installed, run the following to
14. If you have the [GitHub command line tool][] installed, run the following to
create a public Gist for the manifest file:

```shell
Expand All @@ -336,7 +346,7 @@ slightly different steps. We'll call attention where the steps differ.

Or you may go to https://gist.github.com to create it manually.

14. Copy the tarballs (using scp, rsync, etc.) to your `public_html/` folder on
15. Copy the tarballs (using scp, rsync, etc.) to your `public_html/` folder on
downloads.php.net.

```shell
Expand All @@ -347,10 +357,10 @@ slightly different steps. We'll call attention where the steps differ.
> If you do not have a `public_html` directory, create it and set its
> permissions to `0755`.

15. Now the tarballs and signatures may be found at
16. Now the tarballs and signatures may be found at
`https://downloads.php.net/~yourname/`, e.g. https://downloads.php.net/~derick/.

16. Once the release is tagged, contact the release-managers@php.net distribution
17. Once the release is tagged, contact the release-managers@php.net distribution
list so that Windows binaries can be created. Once those are made, they may
be found at https://windows.php.net/qa/.

Expand Down Expand Up @@ -519,8 +529,8 @@ slightly different steps. We'll call attention where the steps differ.

> 💬 **Hint** \
> You should have created this branch when packaging the non-stable release
> candidate for this version. If it is for a PHP-X.Y.0 version, then just
> create and push this branch.
> candidate for this version. If it is for a PHP-X.Y.0 version, then the branch
> was created as part of the final planned release candidate, PHP-X.Y.0RC4.

2. If a CVE commit needs to be merged to the release, have it committed to
the base branches and [merged upwards as usual][] (e.g. commit the CVE fix
Expand Down Expand Up @@ -938,13 +948,20 @@ feature development that cannot go into the new version.
See [Prepare for PHP 8.2][] and [Prepare for PHP 8.2 (bis)][] for an example
of what this commit should include.

4. Push the new version branch and the changes to the `master` branch, with an
> 💬 **Hint** \
> The API version numbers in `Zend/zend_extensions.h`, `Zend/zend_modules.h`, and
> `main/php.h` in `master` need to be **greater** than the ones in the new `PHP-X.Y`
> branch. Generally, use the `YYYYMMDD` date for the *Thursday* as the value for the
> `PHP-X.Y` API numbers, and for the *Friday* as the value for the `master` API
> numbers. This ensures that `master` is always considered newer than the version branch.

5. Push the new version branch and the changes to the `master` branch, with an
appropriate commit message (e.g., "master is now for PHP 8.3.0-dev").

5. Immediately notify internals@ of the new branch and advise on the new merging
6. Immediately notify internals@ of the new branch and advise on the new merging
order. For example: https://news-web.php.net/php.internals/99903

6. Update `web-php:git.php` and https://wiki.php.net/vcs/gitworkflow to reflect
7. Update `web-php:git.php` and https://wiki.php.net/vcs/gitworkflow to reflect
the new branch.

For example:
Expand All @@ -959,6 +976,29 @@ feature development that cannot go into the new version.
> minor improvements and bug fixes. All major improvements and new features must
> wait.

8. Most CI configuration is maintained on the lowest supported branch; update the
applicable files there to reflect the branch cut, and then upmerge that commit
5 times to get it to `master`. The following files need to be updated:

* `.github/nightly_matrix.php` (add new branch, update version for `master`)
[Updating after 8.5 branch cut](https://github.com/php/php-src/commit/197921a8aa7b2f9af103b439bf913e23d6ed1b98)

* `.github/scripts/windows/find-target-branch.bat` (update version for `master`)
[Updating after 8.5 branch cut](https://github.com/php/php-src/commit/107075605db6f1b15ce275e345d1c6de04a464b0)

9. Update the `.github/workflows/push.yml` file with the new branch. This file
does not need to be updated on the lowest supported branch; just update the
newly cut branch to add the new branch to the branches that the workflow
runs on (and then upmerge once to `master`). For example:

* [Updating after 8.5 branch cut](https://github.com/php/php-src/commit/77af4780ccbbc96a2f85a3102d45a15f5e26f9c9)

10. Update the version of `php/php-sdk-binary-tools` used for the `master` branch for the `nightly`
and `push` jobs to account for the new version; this can be done before the branch cut if
the new version is ready. If the new version is not ready when the branch is cut, file an
issue reporting the problem. For example:

* [Updating after 8.5 branch cut](https://github.com/php/php-src/commit/f7e39a91d5a9de53fc4e184f6fce6116ca3388a1)

## Preparing for the initial stable version (PHP X.Y.0)

Expand Down