1# PHP Release Process 2 3A release manager's role includes making packaged source code from the canonical 4repository available according to the release schedule. 5 6The release schedule for each version is published on the 7[PHP wiki](https://wiki.php.net): 8 9- [PHP 8.3](https://wiki.php.net/todo/php83) 10- [PHP 8.2](https://wiki.php.net/todo/php82) 11- [PHP 8.1](https://wiki.php.net/todo/php81) 12- [PHP 8.0](https://wiki.php.net/todo/php80) 13 14The PHP project publishes builds every two weeks. 15 16We publish [general availability][] (GA) releases for major and minor versions of 17PHP on the fourth Thursday of November each year. Following the GA release, we 18publish patch-level releases every four weeks, with at least one release 19candidate (RC) published two weeks before each patch-level release. 20 21Each major and minor version undergoes a 24-week pre-release cycle before GA 22release. The pre-release cycle begins on the second Thursday of June with the 23first alpha release of the new major/minor version. The pre-release cycle 24consists of at least: 25 26- 3 alpha releases 27- 3 beta releases 28- 6 release candidates 29 30Feature freeze for the next major/minor occurs with the first beta release. 31 32We refer to alpha, beta, and RC as *non-stable releases*, while GA are *stable*. 33 34The process of making packaged source available and announcing availability is 35explained in detail below. The process differs slightly for non-stable and 36stable releases. 37 38New release managers should review [New release manager 39checklist](#new-release-manager-checklist) at the end of this document. This 40section explains the procedures for getting ready to begin work on managing PHP 41releases. 42 43 44## General notes and tips 45 461. Do not release on Fridays, Saturdays, or Sundays as this gives poor lead 47 time for downstream consumers adhering to a typical work week. 48 49 Our general procedure is to release on Thursdays, whenever possible. 50 512. Package two days before a release. 52 53 If the release is to be on Thursday, package on Tuesday. Think about 54 timezones as well. 55 563. Ensure that the relevant tests on CI are green. 57 58 - https://travis-ci.com/github/php/php-src 59 - https://cirrus-ci.com/github/php/php-src 60 - https://github.com/php/php-src/actions 61 62 > **Tip** \ 63 > We recommend checking the build status a couple of days before packaging day 64 > to allow enough time to investigate failures, communicate with the authors, 65 > and commit any fixes. 66 > 67 > Check the CI status for your branch periodically and resolve the failures 68 > ASAP. 69 > 70 > See more in https://wiki.php.net/rfc/travis_ci. 71 724. Follow all steps to the letter. 73 74 > **Tip** \ 75 > When you are unsure about anything, ask a previous RM before proceeding. 76 > Ideally, make sure a previous RM is available to answer questions during 77 > the first few releases of your version. For the steps related to the 78 > `web-php`, `web-qa`, and `web-php-distributions` repositories, try to have 79 > someone from the webmaster team on hand. 80 815. Verify the tags to be extra sure everything was tagged properly. 82 836. There is a PHP release Docker image https://github.com/sgolemon/php-release 84 with forks available to help with releases. 85 867. Communicate with release managers via release-managers@php.net. 87 888. References to repositories in this document refer to the canonical source 89 located at https://github.com/php. 90 919. It might be helpful to name your remote repositories something other than 92 "origin" to avoid accidentally pushing changes to "origin" with [muscle 93 memory][]. 94 9510. It might also be helpful to set up conditional includes in your global 96 `~/.gitconfig` to set the proper `user.name`, `user.email`, and 97 `user.signingKey` values to use with your local PHP repositories. See 98 [Conditional Includes For Git Config][] for more information. 99 100 101## Packaging a non-stable release (alpha/beta/RC) 102 103All releases during the pre-release cycle (alpha/beta/RC) leading up to the GA 104release for a version are *non-stable* releases. Following the GA release, all 105RCs are *non-stable* releases. 106 107All non-stable releases follow a similar pattern, though pre-GA releases have 108slightly different steps. We'll call attention where the steps differ. 109 1101. Check that CI is passing (see above). 111 1122. Run `./scripts/dev/credits` in php-src and commit the changes to the credits 113 files in `ext/standard`. 114 115 > **Hint** \ 116 > It's rare this script will make any changes, so if you run `git diff` 117 > and do not see anything, there's no need to panic. That means there are no 118 > changes to the credits files. 119 1203. Check out the *release branch* for this release from the *version branch*. 121 122 > **Non-stable version branches: pre-GA** \ 123 > There is no *version branch* for alpha or beta releases. Instead, treat the 124 > main branch as the version branch. You will create a local-only release 125 > branch from the main branch. Do not push it! 126 > 127 > ```shell 128 > git checkout -b php-X.Y.0alpha1-local-release-branch upstream/master 129 > ``` 130 > 131 > During the first RC release, you will create (and push!) the version 132 > branch for the pre-GA release, e.g., `PHP-8.2`. See 133 > "[Forking a new version branch](#forking-a-new-version-branch)" below. 134 > From this point forward, all pre-GA release branches will be created from 135 > this version branch. Again, these release branches are local-only. Do not 136 > push them! 137 > 138 > ```shell 139 > git checkout -b php-X.Y.0beta2-local-release-branch upstream/PHP-X.Y 140 > ``` 141 142 > **Non-stable version branches: post-GA** \ 143 > After GA, you will create (and push) a new *patch-level version branch* 144 > along with each non-stable release. For example, if you are building a 145 > release for PHP 8.2.8 RC1, you will create the `PHP-8.2.8` patch-level 146 > version branch from the `PHP-8.2` version branch. 147 > 148 > ```shell 149 > git checkout -b PHP-X.Y.Z upstream/PHP-X.Y 150 > git push upstream PHP-X.Y.Z 151 > ``` 152 > 153 > We will use the patch-level version branch to commit any critical bug or 154 > security fixes before this version's GA. 155 > 156 > Then, from the patch-level version branch, you will create another 157 > local-only release branch. Do not push this one! 158 > 159 > ```shell 160 > git checkout -b php-X.Y.ZRC1-local-release-branch upstream/PHP-X.Y.Z 161 > ``` 162 1634. Using your local-only release branch, bump the version numbers in 164 `main/php_version.h`, `Zend/zend.h`, `configure.ac`, and possibly 165 `NEWS`. 166 167 For examples, see [Update versions for PHP 8.1.0beta3][] (for a pre-GA 168 example) or [Update versions for PHP 8.1.6RC1][] along with 169 [Update NEWS for PHP 8.1.6RC1][] (for a post-GA example). 170 171 > ⚠️ **Important** \ 172 > Do not use abbreviations for alpha or beta. Do not use dashes as 173 > separators. 174 > 175 > Do this: 176 > 177 > ```c 178 > #define PHP_VERSION "7.4.22RC1" 179 > ``` 180 > 181 > Not this: 182 > 183 > ```c 184 > #define PHP_VERSION "7.4.22-RC1" 185 > ``` 186 187 > **Note** \ 188 > We update `Zend/zend.h` only when preparing RC and GA releases. We do not 189 > update `ZEND_VERSION` for alpha or beta releases. 190 191 > **API version bump for pre-GA** \ 192 > When releasing the *first release candidate* of a pre-GA release, you must 193 > also bump the API version numbers in `Zend/zend_extensions.h`, 194 > `Zend/zend_modules.h`, and `main/php.h`. See [Prepare for PHP 8.1.0RC1][], 195 > for example. 196 > 197 > The API versions between the alpha, beta, and X.Y.0RCn releases may remain 198 > the same, or be bumped as little as possible because PHP extensions need to 199 > be rebuilt with each bump. 200 > 201 > Do *not* bump the API versions after RC1. 202 2035. Compile and run `make test`, with and without ZTS (Zend Thread Safety), using 204 the correct Bison and re2c versions, e.g., for PHP 7.4, Bison 3.0.0 and re2c 205 0.13.4 are required, as a minimum. 206 207 For example: 208 209 ```shell 210 # With ZTS 211 make distclean || \ 212 ./buildconf --force \ 213 && ./configure --enable-zts --disable-all --enable-debug --enable-opcache --enable-opcache-jit \ 214 && make -j$(nproc) \ 215 && make test TEST_PHP_ARGS="-q -j$(nproc)" \ 216 || ./sapi/cli/php -v 217 218 # Without ZTS 219 make distclean || \ 220 ./buildconf --force \ 221 && ./configure --disable-all --enable-debug --enable-opcache --enable-opcache-jit \ 222 && make -j$(nproc) \ 223 && make test TEST_PHP_ARGS="-q -j$(nproc)" \ 224 || ./sapi/cli/php -v 225 ``` 226 2276. After each build, check the output of `./sapi/cli/php -v` to ensure the 228 versions match the release. 229 2307. If all is correct, commit the changes to your local-only release branch. 231 232 ```shell 233 git add -p 234 git commit --gpg-sign=YOURKEYID -m "Update versions for PHP X.Y.ZRCn" 235 ``` 236 2378. Tag your local-only release branch with the release version. 238 239 ```shell 240 git tag -s -u YOURKEYID php-X.Y.ZRCn -m "Tag for php-X.Y.ZRCn" 241 ``` 242 2439. **For post-GA releases only,** switch back to the *version branch* for 244 your release (e.g., `PHP-8.2`) and bump the version numbers in 245 `main/php_version.h`, `Zend/zend.h`, `configure.ac` and `NEWS`. This prepares 246 the version branch for the next version. 247 248 For example, if the RC is `8.2.1RC1` then the version numbers in the version 249 branch should be bumped to `8.2.2-dev`. We do this regardless of whether we 250 build a new RC to make sure `version_compare()` works correctly. See 251 [Bump for 8.1.8-dev][] for a real example. 252 253 Commit the changes to the version branch. 254 255 ```shell 256 git add -p 257 git commit --gpg-sign=YOURKEYID -m "PHP-X.Y is now for PHP X.Y.Z-dev" 258 ``` 259 260 > **Tip** \ 261 > Version branches (e.g. `PHP-8.1`) will *always* have version numbers in 262 > `main/php_version.h`, `Zend/zend.h`, and `configure.ac` that end in `-dev`. 263 > Patch-level version branches (e.g. `PHP-8.1.7`) will also *always* have 264 > version numbers that end in `-dev` in these files. The main branch (i.e. 265 > `master`) will *always* have version numbers that end in `-dev` in these 266 > files. 267 > 268 > Only release tags should have version numbers in these files that do not 269 > end in `-dev` (e.g., `8.1.7`, `8.1.7RC1`, `8.2.0alpha1`, etc.). 270 27110. Push the changes to the `php-src`. 272 273 ```shell 274 git push upstream php-X.Y.ZRCn # tag name 275 git push upstream PHP-X.Y.Z # patch-level version branch (post-GA only) 276 git push upstream PHP-X.Y # version branch 277 ``` 278 279 > **Attention** \ 280 > Do not push with `--tags`, as this will push all local tags, including 281 > tags you might not wish to push. 282 > 283 > Local-only release branches should not be pushed! 284 28511. Run the following using the release tag to export the tree, create the 286 `configure` script, and build and compress three tarballs (`.tar.gz`, 287 `.tar.bz2` and `.tar.xz`). 288 289 ```shell 290 ./scripts/dev/makedist php-X.Y.ZRCn 291 ``` 292 29312. Run the following using the release tag and your GPG key ID to sign the 294 tarballs and save the signatures to `php-X.Y.ZRCn.manifest`, which you can 295 upload to GitHub and include in the announcement emails. 296 297 ```shell 298 ./scripts/dev/gen_verify_stub X.Y.ZRCn YOURKEYID > php-X.Y.ZRCn.manifest 299 ``` 300 30113. If you have the [GitHub command line tool][] installed, run the following to 302 create a public Gist for the manifest file: 303 304 ```shell 305 gh gist create --public php-X.Y.ZRCn.manifest 306 ``` 307 308 Or you may go to https://gist.github.com to create it manually. 309 31014. Copy the tarballs (using scp, rsync, etc.) to your `public_html/` folder on 311 downloads.php.net. 312 313 ```shell 314 scp php-X.Y.ZRCn.tar.* downloads.php.net:~/public_html/ 315 ``` 316 317 > **Hint** \ 318 > If you do not have a `public_html` directory, create it and set its 319 > permissions to `0755`. 320 32115. Now the tarballs and signatures may be found at 322 `https://downloads.php.net/~yourname/`, e.g. https://downloads.php.net/~derick/. 323 32416. Once the release is tagged, contact the release-managers@php.net distribution 325 list so that Windows binaries can be created. Once those are made, they may 326 be found at https://windows.php.net/qa/. 327 328 Here is an example "ready for builds" message to release-managers@php.net: 329 330 ```text 331 Subject: PHP 8.1.6RC1 ready for builds 332 333 Hi, all! 334 335 Tag: php-8.1.6RC1 336 Tarballs: https://downloads.php.net/~ramsey/ 337 Manifest: https://gist.github.com/ramsey/5d73f0717effb6d8d17699381361e4b1 338 339 Cheers, 340 Ben 341 342 << PASTE FULL MANIFEST CONTENTS HERE >> 343 ``` 344 345 346## Announcing a non-stable release (alpha/beta/RC) 347 3481. Switch to your local clone of the `web-qa` repository and update the 349 information in the `$QA_RELEASES` array in `include/release-qa.php`. 350 351 Follow the documentation in the file for editing the QA release information. 352 See also [Announce 8.1.0RC3][] and [8.1.6RC1][] for examples. 353 354 Add, commit, and push your changes, when finished. 355 356 ```shell 357 git add -p 358 git commit --gpg-sign=YOURKEYID -m "Announce PHP X.Y.ZRCn" 359 git push upstream master 360 ``` 361 3622. **For pre-GA releases only,** add a short notice to `web-php` stating 363 there is a new release, and highlight the major changes (e.g., security 364 fixes). 365 366 To help produce the files for this, use the `bin/createNewsEntry` tool. When 367 you run it, it will ask several questions (see below). For pre-GA non-stable 368 releases, use only the "frontpage" category. 369 370 ```shell 371 cd /path/to/repos/php/web-php 372 ./bin/createNewsEntry 373 # Please type in the title: PHP X.Y.0 Alpha n available for testing 374 # Categories: 375 # 0: PHP.net frontpage news [frontpage] 376 # 1: New PHP release [releases] 377 # 2: Conference announcement [conferences] 378 # 3: Call for Papers [cfp] 379 # Please select appropriate categories, separated with space: 0 380 # Will a picture be accompanying this entry? no 381 # And at last; paste/write your news item here. 382 # To end it, hit <enter>.<enter> 383 # 384 # [[ Here you will paste the full HTML of the post. ]] 385 # . 386 # 387 git add -p 388 git add archive/entries/*.xml 389 git commit --gpg-sign=YOURKEYID -m "Announce PHP X.Y.0RCn" 390 git push upstream master 391 ``` 392 393 Each news entry for pre-GA releases will be similar, though we change the 394 text slightly to indicate progression through the pre-release cycle. For 395 example, here are all the news posts for the pre-GA releases of PHP 8.1.0: 396 397 * [Announce 8.1.0alpha1](https://github.com/php/web-php/commit/57b9675c8d8550493289fa1fba77427c93cdd472) 398 * [Announce 8.1.0alpha2](https://github.com/php/web-php/commit/cec044fc0763f5cfa77d0e79479f8b6279023570) 399 * [Announce 8.1.0alpha3](https://github.com/php/web-php/commit/5c480765f444a3fddfd575e01fe0be3fcfdde05b) 400 * [Announce 8.1.0beta1](https://github.com/php/web-php/commit/40840e3c3f89d6dd95baa4b8cdf22d6f206f86c2) 401 * [Announce 8.1.0beta2](https://github.com/php/web-php/commit/7bf6acdadd4940bd9db711bf3f9d5a4054dc0722) 402 * [Announce 8.1.0beta3](https://github.com/php/web-php/commit/38c8a872700fb0c2ebde49e2eae3374257ba6d08) 403 * [Announce 8.1.0RC1](https://github.com/php/web-php/commit/6e4bf3d0228ce113728d5f1a769ed42e0d63ca10) 404 * [Announce 8.1.0RC2](https://github.com/php/web-php/commit/1ae95f4b686a5d614a94a664a7466ee0e5cd21eb) 405 * [Announce 8.1.0RC3](https://github.com/php/web-php/commit/3091246d77a3f445fcc593587597d0abcab8c373) 406 * [Announce 8.1.0RC4](https://github.com/php/web-php/commit/fbaeb9403f4e2856115889946d3f63751e183c7b) 407 * [Announce 8.1.0RC5](https://github.com/php/web-php/commit/46473ccccfb5f7fedc3f169c55fb7c22a596b55d) 408 * [Announce 8.1.0RC6](https://github.com/php/web-php/commit/cacaef9c41352b5dbf3fbbf44702cc6c0cbfb478) 409 410 > ⚠️ **Important** \ 411 > In your announcement news entry, be sure to include the following text or 412 > text similar to the following: 413 > 414 > > Please DO NOT use this version in production, it is an early test version. 415 416 > **Note** \ 417 > When a version is in its post-GA phase, we do not post news entries for 418 > non-stable releases. 419 4203. Wait for the web and qa sites to update with the new information before 421 sending announcements. This could take up to an hour. 422 4234. Send *separate* announcement emails to: 424 425 * `internals@lists.php.net` 426 * `php-general@lists.php.net` 427 * `php-qa@lists.php.net` 428 429 In the announcement message, point out the location of the release and the 430 possible release date of either the next RC or the final release. Also 431 include the manifest generated by `gen_verify_stub` when you packaged the 432 build. 433 434 Here are a few examples of non-stable release announcement emails: 435 436 * [PHP 8.1.0alpha1 is available for testing](https://news-web.php.net/php.qa/69043) 437 * [PHP 8.1.0beta3 available for testing](https://news-web.php.net/php.qa/69079) 438 * [PHP 8.1.0RC6 available for testing](https://news-web.php.net/php.qa/69117) 439 * [PHP 8.1.7RC1 Ready for testing](https://news-web.php.net/php.qa/69163) 440 441 > **Send separate emails!** \ 442 > Do *not* send a single email message with all addresses in the `To`, `Cc`, 443 > or `Bcc` headers. If a user replies to one of these messages, we do not 444 > want their email client to automatically send the reply to each list, as 445 > often occurs. 446 447 > **Hint** \ 448 > We send emails to the followers of these mailing lists to notify them of 449 > new releases, so they can make sure their projects keep working and can 450 > report any potential bugs that should be fixed before the upcoming GA 451 > release. 452 4535. **For pre-GA *RCs* only,** coordinate with the social media team (i.e., 454 Derick) to post a tweet with the RC release announcement and link to the news 455 entry on php.net. ([@official_php](https://twitter.com/official_php)) 456 457 458## Packaging a stable release 459 4601. Check out the *patch-level version branch* for the release 461 (e.g., `PHP-8.1.7`). 462 463 > **Hint** \ 464 > You should have created this branch when packaging the non-stable release 465 > candidate for this version. 466 4672. If a CVE commit needs to be merged to the release, have it committed to 468 the base branches and [merged upwards as usual][] (e.g. commit the CVE fix 469 to 7.2, merge to 7.3, 7.4, etc.). Then, you can cherry-pick it into the 470 patch-level version branch for this release. 471 472 Commit these changes and push the patch-level version branch. Ensure 473 that CI is still passing (see above). 474 475 > **Tip** \ 476 > Don't forget to update `NEWS` manually in an extra commit to the 477 > patch-level version branch. 478 4793. Run the `./scripts/dev/credits` script in the patch-level version branch, 480 and commit the changes in the credits files in `ext/standard`. 481 482 > **Note** \ 483 > It's very rare this will make changes at this point, but we run it here 484 > in case the credits changed as a result of a bug fix that was 485 > cherry-picked into this branch. 486 4874. Create a local-only release branch for this release from the *patch-level 488 version branch*. 489 490 ```shell 491 git checkout -b php-X.Y.Z-local-release-branch upstream/PHP-X.Y.Z 492 ``` 493 4945. Using your local-only release branch, bump the version numbers in 495 `main/php_version.h`, `Zend/zend.h`, `configure.ac`, and possibly 496 `NEWS`. 497 498 For example, if you're releasing a stable version for PHP 8.1.8, then all 499 the version numbers in the patch-level version branch should be 500 `8.1.8-dev`. In your local-only release branch, you will change them all to 501 `8.1.8`. 502 503 See [Update versions for PHP 8.1.7][] and [Update NEWS for PHP 8.1.7][] for 504 an example. 505 5066. Compile and run `make test`, with and without ZTS (Zend Thread Safety), using 507 the correct Bison and re2c versions, e.g., for PHP 7.4, Bison 3.0.0 and re2c 508 0.13.4 are required, as a minimum. 509 510 For example: 511 512 ```shell 513 # With ZTS 514 make distclean || \ 515 ./buildconf --force \ 516 && ./configure --enable-zts --disable-all --enable-debug --enable-opcache --enable-opcache-jit \ 517 && make -j$(nproc) \ 518 && make test TEST_PHP_ARGS="-q -j$(nproc)" \ 519 || ./sapi/cli/php -v 520 521 # Without ZTS 522 make distclean || \ 523 ./buildconf --force \ 524 && ./configure --disable-all --enable-debug --enable-opcache --enable-opcache-jit \ 525 && make -j$(nproc) \ 526 && make test TEST_PHP_ARGS="-q -j$(nproc)" \ 527 || ./sapi/cli/php -v 528 ``` 529 5307. After each build, check the output of `./sapi/cli/php -v` to ensure the 531 versions match the release. 532 5338. If all is correct, commit the changes to your local-only release branch. 534 535 ```shell 536 git add -p 537 git commit --gpg-sign=YOURKEYID -m "Update versions for PHP X.Y.Z" 538 ``` 539 5409. Tag your local-only release branch with the release version and push the tag. 541 542 ```shell 543 git tag -s -u YOURKEYID php-X.Y.Z -m "Tag for php-X.Y.Z" 544 git push upstream php-X.Y.Z 545 ``` 546 54710. Run the following using the release tag to export the tree, create the 548 `configure` script, and build and compress three tarballs (`.tar.gz`, 549 `.tar.bz2` and `.tar.xz`). 550 551 ```shell 552 ./scripts/dev/makedist php-X.Y.Z 553 ``` 554 555 > **Hint** \ 556 > Check if the PEAR files are updated (Phar). 557 558 > **Tip** \ 559 > On some systems the behavior of GNU tar can default to produce POSIX 560 > compliant archives with PAX headers. As not every application is 561 > compatible with that format, creation of archives with PAX headers should 562 > be avoided. When packaging on such a system, the GNU tar can be influenced 563 > by defining the environment variable `TAR_OPTIONS='--format=gnu'`. 564 56511. Run the following using the release tag and your GPG key ID to sign the 566 tarballs and save the signatures to `php-X.Y.Z.manifest`, which you can 567 upload to GitHub and include in the announcement emails. 568 569 ```shell 570 ./scripts/dev/gen_verify_stub X.Y.Z YOURKEYID > php-X.Y.Z.manifest 571 ``` 572 57312. If you have the [GitHub command line tool][] installed, run the following to 574 create a public Gist for the manifest file: 575 576 ```shell 577 gh gist create --public php-X.Y.Z.manifest 578 ``` 579 580 Or you may go to https://gist.github.com to create it manually. 581 58213. Switch to your local clone of the `web-php-distributions` repository and 583 copy the tarballs and signature files into the repository. Add, commit, and 584 push them. 585 586 ```shell 587 cd /path/to/repos/php/web-php-distributions 588 mv /path/to/repos/php/php-src/php-X.Y.Z.tar.* . 589 git add php-X.Y.Z.tar.* 590 git commit --gpg-sign=YOURKEYID -m "Add tarballs for php-X.Y.Z" 591 git push upstream master 592 ``` 593 59414. Switch to your local clone of the `web-php` repository and update the 595 `web-php-distributions` submodule. 596 597 ```shell 598 cd /path/to/repos/php/web-php 599 git pull --rebase upstream master 600 git submodule init 601 git submodule update 602 cd distributions 603 git fetch --all 604 git pull --rebase upstream master 605 cd .. 606 git commit distributions -m "X.Y.Z tarballs" 607 git push upstream master 608 ``` 609 610 > **Hint** \ 611 > This fetches the last commit ID from `web-php-distributions` and pins the 612 > "distributions" submodule in `web-php` to this commit ID. 613 > 614 > When the website syncs, which should happen within an hour, the tarballs 615 > will be available from `https://www.php.net/distributions/php-X.Y.Z.tar.gz`, 616 > etc. 617 61815. Once the release is tagged, contact the release-managers@php.net distribution 619 list so that Windows binaries can be created. Once those are made, they may 620 be found at https://windows.php.net/qa/. 621 622 > ⚠️ **Important** \ 623 > Do *not* send this announcement to any public lists. 624 625 Here is an example "ready for builds" message to release-managers@php.net: 626 627 ```text 628 Subject: PHP 8.1.6 ready for builds 629 630 Hi, all! 631 632 Tag: php-8.1.6 633 Tarballs: web-php-distributions 634 Manifest: https://gist.github.com/ramsey/432fcf8afcbfb1f1de6c3ab47d82e366 635 636 Cheers, 637 Ben 638 639 << PASTE FULL MANIFEST CONTENTS HERE >> 640 ``` 641 642 643## Announcing a stable release 644 6451. Switch to your local clone of `web-php` and add the information for the 646 previous release to `include/releases.inc`. 647 648 For example, if you are preparing to announce version 8.2.2, then the 649 previous release is 8.2.1, so you will add the information for 8.2.1 to this 650 file. Most of the time, you can do this using the `bin/bumpRelease` tool. 651 652 ```shell 653 ./bin/bumpRelease 8 2 654 ``` 655 656 The first number is the major version, and the second number is the minor 657 version. In this example, we're bumping the release information for version 658 8.2. There is no need to provide the patch level. 659 660 > **Tip** \ 661 > If this fails for any reason, you can manually copy the information 662 > for the previous release from `include/version.inc` into 663 > `include/releases.inc`. 664 6652. Update the version information for the new release in `include/version.inc`. 666 667 Find the part of the `$data` array that is related to your version (e.g., 668 `$data['8.2']` for 8.2.x releases), and make the following edits: 669 670 * Set `version` to the full version number (e.g. '8.2.1') 671 * Set `date` to the release date in `j M Y` format (e.g. '5 Jan 2021') 672 * Update the `tags` array to include `'security'` if this is a security release 673 * Update the `sha256` array with the hashes for each of the release tarballs 674 6753. Create the release file and news entry for the new version. 676 677 ```shell 678 ./bin/createReleaseEntry -v X.Y.Z -r # --security for security releases 679 ``` 680 681 This will create a release file (i.e., `releases/X_Y_Z.php`) and a news entry 682 file (i.e., `archive/entries/YYYY-MM-DD-n.xml`), while also updating 683 `archive/archive.xml`. 684 685 Within these files, it will generate standard messages for the new version. 686 You may edit the generated files to expand on the base message, if needed. 687 6884. Update the ChangeLog file for the given major version (e.g., `ChangeLog-8.php`). 689 690 ```shell 691 ./bin/news2html 'https://github.com/php/php-src/raw/php-X.Y.Z/NEWS' 'X.Y.Z' 'ChangeLog-X.php' 692 ``` 693 6945. Review all the changes in `web-php`, commit, and push them. 695 696 ```shell 697 git add -p 698 git add archive/entries/*.xml releases/*.php 699 git commit --gpg-sign=YOURKEYID -m "Announce PHP X.Y.Z" 700 git push upstream master 701 ``` 702 703 See [Announce PHP 8.1.6][] for an example commit. 704 7056. Switch to your local clone of the `web-qa` repository and update the 706 information in the `$QA_RELEASES` array in `include/release-qa.php`. 707 708 The array probably contains information about the RC released two weeks ago 709 in preparation for the current release. Since the current release is now GA, 710 it's time to remove the RC build from the QA website. 711 712 It is sufficient to set the `number` property for the release to `0` to 713 stop displaying the RC build on the QA website. You may also remove the 714 sha256 hashes for the RC tarballs, but it's not necessary. For an example, 715 see [PHP 8.1.6 released][]. 716 717 Add, commit, and push your changes, when finished. 718 719 ```shell 720 git add -p 721 git commit --gpg-sign=YOURKEYID -m "PHP X.Y.Z released" 722 git push upstream master 723 ``` 724 7257. **Before sending announcement emails, check to make sure the websites have 726 synced.** 727 728 * Make sure the tarballs are available from, e.g., 729 `https://www.php.net/distributions/php-X.Y.Z.tar.gz` 730 * Check the "downloads" page to make sure the new version appears: 731 https://www.php.net/downloads 732 * Does the news entry show up on the home page? https://www.php.net 733 * Do the updates to the ChangeLog appear? 734 e.g., https://www.php.net/ChangeLog-8.php 735 * Is there a release page for the new version? 736 e.g., `https://www.php.net/releases/X_Y_Z.php` 737 * Does the RC for this version still appear on the QA home page? 738 https://qa.php.net 739 740 Keep in mind it may take up to an hour for the websites to sync. 741 7428. Please note down the sha256 and the PGP signature (.asc). These *must* be 743 included in the release mail. 744 7459. Send *separate* announcement emails to: 746 747 * `php-announce@lists.php.net` 748 * `php-general@lists.php.net` 749 * `internals@lists.php.net` 750 751 Release announcement emails must include the manifest generated when 752 packaging the build, along with links to the sources, Windows binaries, and 753 changelog. Here are a few examples of stable release announcement emails: 754 755 * [PHP 8.1.0 Released](https://news-web.php.net/php.announce/321) 756 * [PHP 8.1.3 Released](https://news-web.php.net/php.announce/325) 757 * [PHP 8.1.6 Released](https://news-web.php.net/php.announce/331) 758 759 > ⚠️ **Important** \ 760 > For standard patch-level releases, we will note "This is a bugfix release." 761 > If it is a security release, we must note "This is a security release." 762 763 > **Send separate emails!** \ 764 > Do *not* send a single email message with all addresses in the `To`, `Cc`, 765 > or `Bcc` headers. If a user replies to one of these messages, we do not 766 > want their email client to automatically send the reply to each list, as 767 > often occurs. 768 76910. Coordinate with the social media team (i.e., Derick) to post a tweet with 770 the release announcement and link to the news entry on php.net. 771 ([@official_php](https://twitter.com/official_php)) 772 773 774## Re-releasing the same version or a patch-level (i.e., `-plN`) 775 776While unlikely, there may be times we need to re-release the same version. This 777might happen if the tarballs have a corrupted file, for example. 778 779Should this occur *before* announcing the release, you may choose to delete the 780tag and go through the full packaging process again, as described above. 781 782> **Hint** \ 783> This is one of the reasons we package releases two days before announcing 784> them. 785 786If this happens *after* announcing the release, you may choose to tag, package, 787and release a patch-level (i.e., *pl*) release. If it is not critical and/or 788affects a very limited subset of users, then you may choose to wait until the 789next release. 790 791If you choose to create a patch-level release, follow these steps: 792 7931. Commit the new binaries to `web-php-distributions` 794 7952. Update $data['X.Y'] in `web-php:/include/version.inc` 796 (X.Y=major.minor release, e.g. '8.0'): 797 798 * `version` to the full version number (e.g. '8.0.1-pl1') 799 * `date` to the release date in `j M Y` format (e.g. '9 Jan 2021') 800 * `tags` array should include `security` if this is a security release 801 * `sha256` array and sub-elements for all SHA256 sums 802 8033. Add a short notice to `web-php` stating that there is a new release, and 804 highlight the major important things (security fixes) and when it is 805 important to upgrade. 806 807 * Call `php bin/createReleaseEntry -v <version> [ --security ]` in your 808 local web-php checkout. 809 8104. Commit all the changes (`include/version.inc`, `archive/archive.xml`, 811 `archive/entries/YYYY-MM-DD-N.xml`). 812 8135. Wait an hour or two, then send a mail to php-announce@lists.php.net, 814 php-general@lists.php.net and internals@lists.php.net with a text similar to 815 the news entry. 816 817 Please make sure that the mail to php-announce@ is its own completely 818 separate email. This is to make sure that replies to the announcement on 819 php-general@ or internals@ will not accidentally hit the php-announce@ 820 mailinglist. 821 822 823## Feature freeze 824 825A major/minor version [feature freeze][] occurs with the first beta release. 826Specifically, it occurs when the first beta release is packaged, which means the 827feature freeze occurs two days before the first beta release. 828 829The feature freeze for `php-src` means that we will not accept any new features 830after the date of the feature freeze. For any RFCs to be included in the new 831version, they should be discussed and have the voting polls closed no later than 832the feature freeze date. However, this does not mean the new feature must have a 833complete implementation by this date. 834 835Following the feature freeze, the focus of work for the new version will be on 836fixing bugs, writing tests, and completing/polishing all accepted features. 837 838As a courtesy to the community, the release managers should remind others about 839the upcoming feature freeze by posting reminders to internals@lists.php.net at 8404-weeks, 3-weeks, 2-weeks, and 1-week prior to the feature freeze. This is a 841recommendation and the intervals may vary based on work load. 842 843 844## Forking a new version branch 845 846When the new version has reached the first RC, it is time to create a new 847version branch. This frees up the main branch (i.e., `master`) for any new 848feature development that cannot go into the new version. 849 8501. One week prior to tagging `X.Y.0RC1`, warn internals@ that your version's 851 branch is about to be created. Be specific about when the branch creation 852 will occur. For example: https://news-web.php.net/php.internals/99864 853 8542. Just prior to tagging `X.Y.0RC1`, create the new version branch locally, 855 i.e. `PHP-X.Y`. 856 8573. Add a commit on the main branch (i.e., `master`) after the branch point. 858 859 This commit should: 860 861 * clear the `NEWS`, `UPGRADING`, and `UPGRADING.INTERNALS` files; 862 * update the version numbers in `configure.ac`, `main/php_version.h`, 863 `Zend/zend.h`, and `win32/build/confutils.js`; 864 * update the API version numbers in `Zend/zend_extensions.h`, 865 `Zend/zend_modules.h`, and `main/php.h`; and 866 * add the new branch to the list in `CONTRIBUTING.md`. 867 868 See [Prepare for PHP 8.2][] and [Prepare for PHP 8.2 (bis)][] for an example 869 of what this commit should include. 870 8714. Push the new version branch and the changes to the `master` branch, with an 872 appropriate commit message (e.g., "master is now for PHP 8.3.0-dev"). 873 8745. Immediately notify internals@ of the new branch and advise on the new merging 875 order. For example: https://news-web.php.net/php.internals/99903 876 8776. Update `web-php:git.php` and https://wiki.php.net/vcs/gitworkflow to reflect 878 the new branch. 879 880 For example: 881 882 * [Add PHP-8.1 to the Git steps page][] 883 * [Changes to the wiki][] 884 885> **Hint** \ 886> We create the new version branch at the first release candidate rather than at 887> feature freeze to allow a period of time where the focus is on making the new 888> version ready for RC and GA. During this time, the main branch is *only* for 889> minor improvements and bug fixes. All major improvements and new features must 890> wait. 891 892 893## Preparing for the initial stable version (PHP X.Y.0) 894 8951. When you release the first pre-GA RC, remind the documentation team 896 (phpdoc@lists.php.net) to write the [migration guide][]. Make sure the guide 897 is available before releasing the initial stable version, since you should 898 link to it in the release announcements. 899 9002. Timely get used to the differences in preparing and announcing a stable 901 release. 902 9033. Before releasing X.Y.0, merge the `NEWS` entries of the pre-releases, so that 904 there is only a single section about PHP X.Y.0, instead of individual 905 sections for each pre-release. 906 907 908## Prime the selection of release managers for the next version 909 910About three months prior to the scheduled release of the first alpha release of 911the next minor or major version (around March 1st or shortly thereafter), the 912release managers for the latest version branch should issue a call for 913volunteers to begin the selection process for the next release managers. 914 9151. Issue the call for volunteers on internals@lists.php.net on or around March 916 1st. See, for example: https://news-web.php.net/php.internals/113334 917 918 There is no rule for how long the call for volunteers must remain open. We 919 should aim to select the release managers by early April, so announcing the 920 call in early March gives people about a month to decide whether they wish to 921 volunteer. 922 9232. There should be two or more volunteers. Typically, one should be a veteran 924 release manager (having previously served as a `php-src` release manager), 925 while the other one (or two) should be rookies. Hold a vote if necessary (see 926 https://wiki.php.net/rfc/releaseprocess#release_managers_selection). 927 9283. Help the new release managers with their first steps. 929 930 931## New release manager checklist 932 9331. Email systems@php.net to get setup for access to downloads.php.net and to be 934 added to the release-managers@php.net distribution list. 935 9362. Request membership to the release managers group on GitHub. 937 9383. Create a [GPG key][] for your @php.net address. 939 940 > **Tip** \ 941 > If you're new to GPG, follow GitHub's instructions for 942 > [Generating a new GPG key][]. 943 944 Publish your key by editing `include/gpg-keys.inc` in the `web-php` 945 repository. Add a `case` for your username to the `gpg_key_get()` function, 946 and paste the output from `gpg --fingerprint`. You may also need to update 947 the `$branches` array in the `gpg_key_get_branches()` function to include 948 your username alongside your branch. 949 950 ```console 951 ❯ gpg --fingerprint ramsey@php.net 952 pub rsa4096 2021-04-26 [SC] [expires: 2025-11-24] 953 39B6 4134 3D8C 104B 2B14 6DC3 F9C3 9DC0 B969 8544 954 uid [ultimate] Ben Ramsey <ramsey@php.net> 955 sub rsa4096 2021-04-26 [E] [expires: 2025-11-24] 956 ``` 957 958 Have one or more of the other RMs [sign your GPG key][], and publish your 959 public key to a keyserver: 960 961 ```shell 962 gpg --keyserver keys.openpgp.org --send-keys YOURKEYID 963 gpg --keyserver keyserver.ubuntu.com --send-keys YOURKEYID 964 ``` 965 966 Add your public key to `php-keyring.gpg` in `web-php-distributions`. To do 967 this, you will need to import all keys from the current PHP keyring file to 968 your local GPG keyring. You will need to take note of the key IDs for each of 969 the release managers listed in `php-keyring.gpg`. Then, you will export, 970 specifying your key ID in addition to the key IDs of every other release 971 manager. Save this export back to `php-keyring.gpg`, commit the changes, 972 and push. 973 974 ```shell 975 cd /path/to/repos/php/web-php-distributions 976 gpg php-keyring.gpg # lists all keys in the keyring 977 gpg --import php-keyring.gpg # imports all keys to your local keyring 978 gpg --export \ 979 --export-options export-minimal \ 980 --armor \ 981 YOURKEYID F9C39DC0B9698544 DBDB397470D12172 MORE RM KEY IDS ... \ 982 > php-keyring.gpg 983 gpg php-keyring.gpg # verify all the keys are present, including yours 984 git add -p 985 git commit --gpg-sign=YOURKEYID -m "Update PHP release manager keyring" 986 git push 987 ``` 988 989 `web-php-distributions` is a submodule of `web-php`. You'll now have to update 990 the commit reference to reflect the change made in web-php-distributions. 991 992 ```shell 993 cd /path/to/repos/php/web-php 994 git submodule update 995 cd distributions # This is the submodule refering to web-php-distributions 996 git pull origin master 997 cd .. 998 git add distributions 999 git commit --gpg-sign=YOURKEYID -m "Update php-keyring.gpg in distributions" 1000 git push 1001 ``` 1002 10034. Request moderation access to php-announce@lists.php.net 1004 so you are able to moderate your release announcements. All the announcements 1005 should be sent from your @php.net address. 1006 1007 > **Hint** \ 1008 > To send email from your @php.net address, you will need to use a custom 1009 > SMTP server. If you use Gmail, you may 1010 > "[Send emails from a different address or alias][]." 1011 10125. Make sure you have the following repositories cloned locally: 1013 1014 * https://github.com/php/php-src 1015 * https://github.com/php/web-php 1016 * https://github.com/php/web-qa 1017 * https://github.com/php/web-php-distributions 1018 1019 1020[general availability]: https://en.wikipedia.org/wiki/Software_release_life_cycle#General_availability_(GA) 1021[muscle memory]: https://en.wikipedia.org/wiki/Muscle_memory 1022[Conditional Includes For Git Config]: https://motowilliams.com/2017-05-11-conditional-includes-for-git-config/ 1023[Update versions for PHP 8.1.0beta3]: https://github.com/php/php-src/commit/3edd1087c70bee2ec21f0fbec1a575d78a500f15 1024[Update versions for PHP 8.1.6RC1]: https://github.com/php/php-src/commit/40e8ced23898e3069340ca03ea5febc5361015ad 1025[Update NEWS for PHP 8.1.6RC1]: https://github.com/php/php-src/commit/a4fdeaebe419b88e3b4a1f5aba845c2d4e81fd4e 1026[Prepare for PHP 8.1.0RC1]: https://github.com/php/php-src/commit/5764414eb8900ae98020a3c20693f4fb793efa99 1027[Bump for 8.1.8-dev]: https://github.com/php/php-src/commit/3b6ee1eb19c14c3339ebfcf5c967065a9f828971 1028[GitHub command line tool]: https://cli.github.com 1029[Announce 8.1.0RC3]: https://github.com/php/web-qa/commit/f264b711fd3827803b79bbb342959eae57ea502b 1030[8.1.6RC1]: https://github.com/php/web-qa/commit/e6d61ad7a9d8be0b1cd159af29f3b9cbdde33384 1031[merged upwards as usual]: https://wiki.php.net/vcs/gitworkflow 1032[Update versions for PHP 8.1.7]: https://github.com/php/php-src/commit/d35e577a1bd0b35b9386cea97cddc73fd98eed6d 1033[Update NEWS for PHP 8.1.7]: https://github.com/php/php-src/commit/b241f07f52ca9f87bf52be81817f475e6e727439 1034[Announce PHP 8.1.6]: https://github.com/php/web-php/commit/9f796a96c65f07e45845ec248933bfb0010b94a9 1035[PHP 8.1.6 released]: https://github.com/php/web-qa/commit/bff725f8373cf6fd9d97ba62a8517b19721a4c2e 1036[feature freeze]: https://en.wikipedia.org/wiki/Freeze_(software_engineering) 1037[Prepare for PHP 8.2]: https://github.com/php/php-src/commit/1c33ddb5e5598c5385c4c965992c6e031fd00dd6 1038[Prepare for PHP 8.2 (bis)]: https://github.com/php/php-src/commit/a93e12f8a6dfc23e334339317c97aa35356db821 1039[Add PHP-8.1 to the Git steps page]: https://github.com/php/web-php/commit/1fcd78c2817cf1fbf1a1de2ddec1350be4e26491 1040[Changes to the wiki]: https://wiki.php.net/vcs/gitworkflow?do=diff&rev2%5B0%5D=1617123194&rev2%5B1%5D=1654728193&difftype=sidebyside 1041[migration guide]: https://www.php.net/manual/en/migration81.php 1042[GPG key]: https://en.wikipedia.org/wiki/GNU_Privacy_Guard 1043[Generating a new GPG key]: https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key 1044[sign your GPG key]: https://carouth.com/articles/signing-pgp-keys/ 1045[Send emails from a different address or alias]: https://support.google.com/mail/answer/22370?hl=en 1046