1# PHP release process 2 3A release managers role includes making packaged source code from the canonical repository 4available according to their release schedule. 5 6The release schedule for their branch is available on a Wiki page, for example 7 [PHP 8.0 release schedule](https://wiki.php.net/todo/php80) 8 9There are two types of release: 10 11 - non stable (alpha/beta/RC) 12 - stable 13 14The process of making packaged source available and announcing availability is explained 15in detail below. The process differs slightly for non-stable and stable releases. 16 17Before a release manager can begin their work, there are several things that must happen, 18explained at the end of this document in 19 [New Release Manager Checklist](#new-release-manager-checklist). 20 21## General notes and tips 22 23 1. Do not release on Fridays, Saturdays, or Sundays as this gives poor lead time for 24 downstream consumers adhering to a typical work week. 25 26 2. Package two days before a release. So if the release is to be on Thursday, 27 package on Tuesday. Think about timezones as well. 28 29 3. Ensure that the relevant tests on CI are green. 30 31 See: 32 33 - https://travis-ci.com/github/php/php-src 34 - https://dev.azure.com/phpazuredevops/PHP/ 35 - https://cirrus-ci.com/github/php/php-src 36 37 It is recommended to do so a couple of days before the packaging day, to 38 have enough time to investigate failures, communicate with the authors and 39 commit the fixes. 40 41 Check the CI status for your branch periodically and resolve the failures ASAP. 42 43 See more in https://wiki.php.net/rfc/travis_ci. 44 45 4. Follow all steps to the letter. When unclear ask previous RM's before 46 proceeding. Ideally make sure that for the first releases one of the 47 previous RM's is around to answer questions. For the steps related to the 48 php/QA/bug websites try to have someone from the webmaster team on hand. 49 50 5. Verify the tags to be extra sure everything was tagged properly. 51 52 6. There is a PHP release Docker image https://github.com/sgolemon/php-release 53 with forks available to help releasing. 54 55 7. Communication with previous release managers should be conducted via 56 release-managers@php.net 57 58 8. References to repositories in this document refer to the canonical source 59 located at https://github.com/php 60 61## Packaging a non stable release (alpha/beta/RC) 62 63 1. Check the tests at https://travis-ci.com/php/php-src/builds. 64 65 2. Run the `scripts/dev/credits` script in php-src and commit the changes in 66 the credits files in ext/standard. 67 68 3. Checkout the release branch for this release (e.g., PHP-7.4.2) from the main 69 branch. 70 71 4. Bump the version numbers in `main/php_version.h`, `Zend/zend.h`, 72 `configure.ac` and possibly `NEWS`. Do not use abbreviations for alpha and 73 beta. Do not use dashes, you should `#define PHP_VERSION "7.4.22RC1"` and 74 not `#define PHP_VERSION "7.4.22-RC1"`. 75 76 ⚠️ When releasing the **first release candidate**, you must also bump the API 77 version numbers in `Zend/zend_extensions.h`, `Zend/zend_modules.h`, and 78 `main/php.h`. The API versions between the alpha/beta/.0RCx releases can be 79 left the same, or bumped as little as possible because PHP extensions will 80 need to be rebuilt with each bump. Do *not* bump the API versions after 81 RC1. 82 83 5. Compile and run `make test`, with and without ZTS, using the right Bison and 84 re2c version (for PHP 7.4, minimum Bison 3.0.0 and re2c 0.13.4 are used). 85 86 6. Check `./sapi/cli/php -v` output for version matching. 87 88 7. If all is right, commit the changes to the release branch: 89 90 ```sh 91 git commit -a 92 ``` 93 94 8. Tag the repository release branch with the version, e.g.: 95 96 ```sh 97 git tag -u YOURKEYID php-7.4.2RC2 98 ``` 99 100 9. Bump the version numbers in `main/php_version.h`, `Zend/zend.h`, 101 `configure.ac` and `NEWS` in the *main* branch (PHP-7.4 for example) to 102 prepare for the **next** version. For example, if the RC is "7.4.1RC1" then 103 the new one should be `7.4.2-dev` - regardless if we get a new RC or not. 104 This is to make sure `version_compare()` can correctly work. Commit the 105 changes to the main branch. 106 10710. Push the changes to the `php-src`. 108 109 Non stable release branches don't need to be pushed 110 (a local temporary branch should be used). 111 112 ```sh 113 git push --tags origin HEAD 114 git push origin {main branch} 115 git push origin {release branch} 116 ``` 117 11811. Run: `./scripts/dev/makedist php-7.4.0RC2`, this will export the tree, 119 create `configure` and build three tarballs (gz, bz2 and xz). 120 12112. Run `./scripts/dev/gen_verify_stub <version> [identity]`, this will sign the 122 tarballs and output verification information to be included in announcement 123 email. 124 12513. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there 126 should be a directory `public_html/`. Copy them into there. If you do not 127 have this directory, create it. 128 12914. Now the RC can be found on https://downloads.php.net/~yourname, 130 e.g. https://downloads.php.net/~derick/. 131 13215. Once the release has been tagged, contact the release-managers@ distribution 133 list so that Windows binaries can be created. Once those are made, they can 134 be found at https://windows.php.net/download. 135 136## Announcing a non stable release (alpha/beta/RC) 137 138 1. Update `web-qa:include/release-qa.php` with the appropriate information. See 139 the documentation within release-qa.php for more information, but all 140 releases and RCs are configured here. Only `$QA_RELEASES` needs to be 141 edited. 142 143 Example: When packaging an RC, set the `rc` with appropriate information for 144 the given version. 145 146 Note: Remember to update the sha256 checksum information. 147 148 2. Skip this step for non-stable releases after GA of minor or major versions 149 (e.g. announce 7.4.0RC1, but not 7.4.1RC1): 150 151 Add a short notice to web-php stating that there is a new release, and 152 highlight the major important things (security fixes) and when it is 153 important to upgrade. 154 155 * Call `php bin/createNewsEntry` in your local web-php checkout. Use category 156 "frontpage" *and* "releases" for all stable releases. Use category 157 "frontpage" for X.Y.0 non-stable releases only (news only). 158 159 * Add the content for the news entry. Be sure to include the text: 160 161 ```text 162 "THIS IS A DEVELOPMENT PREVIEW - DO NOT USE IT IN PRODUCTION!" 163 ``` 164 165 3. Commit and push changes to qa and web. 166 167 Wait for web and qa sites to update with new information before sending 168 announce. 169 170 4. Send **separate** emails **To** `internals@lists.php.net` and 171 `php-general@lists.php.net` lists pointing out "the location of the release" 172 and "the possible release date of either the next RC, or the final release". 173 Include in this information the verification information output by 174 `gen_verify_stub`. 175 176 5. Send **separate** emails (see example http://news.php.net/php.pear.qa/5201) 177 **To** `php-qa@lists.php.net` and `primary-qa-tester@lists.php.net`. These 178 emails are to notify the selected projects about a new release so that they 179 can make sure their projects keep working. Make sure that you have been 180 setup as a moderator for `primary-qa-tester@lists.php.net` by having someone 181 (Hannes, Dan, Derick) run the following commands for you: 182 183 ```sh 184 ssh lists.php.net 185 sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester mod moderator-email-address 186 ``` 187 6. For RCs, post tweet with release announcement (and link to news article on 188 php.net) ([@official_php](https://twitter.com/official_php)) 189 190## Packaging a stable release 191 192 1. Checkout your release branch, you should have created when releasing 193 previous RC and bump the version numbers in `main/php_version.h`, 194 `Zend/zend.h`, `configure.ac` and possibly `NEWS`. 195 196 2. If a CVE commit needs to be merged to the release, then have it committed to 197 the base branches and merged upwards as usual (e.g. commit the CVE fix to 198 7.2, merge to 7.3, 7.4 etc...). Then you can cherry-pick it in your release 199 branch. Don't forget to update `NEWS` manually in an extra commit then. 200 201 3. Commit those changes. Ensure the tests at 202 https://travis-ci.com/php/php-src/builds are still passing. 203 204 4. Run the `scripts/dev/credits` script in php-src and commit the changes in 205 the credits files in ext/standard. 206 207 5. Compile and run `make test`, with and without ZTS, using the right Bison and 208 re2c version (for PHP 7.4, minimum Bison 3.0.0 and re2c 0.13.4 are used). 209 210 6. Check `./sapi/cli/php -v` output for version matching. 211 212 7. Tag the repository with the version e.g. `git tag -u YOURKEYID php-7.4.1` 213 214 8. Push the tag e.g. `git push origin php-7.4.1`. 215 216 9. Run: `./scripts/dev/makedist php-7.4.1`, this will export the tag, 217 create configure and build three tarballs (gz, bz2 and xz). Check if the 218 pear files are updated (phar). On some systems the behavior of GNU tar can 219 default to produce POSIX compliant archives with PAX headers. As not every 220 application is compatible with that format, creation of archives with PAX 221 headers should be avoided. When packaging on such a system, the GNU tar can 222 be influenced by defining the environment variable 223 `TAR_OPTIONS='--format=gnu'`. 224 22510. Run `scripts/dev/gen_verify_stub <version> [identity]`, this will sign the 226 tarballs and output verification information to be included in announcement 227 email. 228 22911. Commit and push all the tarballs and signature files to 230 `web-php-distributions`, then update the git submodule reference in 231 `web-php`: 232 233 ```sh 234 git submodule init 235 git submodule update 236 cd distributions 237 git fetch 238 git pull --rebase origin master 239 cd .. 240 git commit distributions 241 git push 242 ``` 243 244 This is to fetch the last commit id from `web-php-distributions` and commit 245 this last commit id to `web-php`, then, website will now sync. 246 24712. Once the release has been tagged, contact release managers, Windows 248 builders, and package maintainers so that they can build releases. Do not 249 send this announcement to any public lists. 250 251## Announcing a stable release 252 253 1. Update `web-php:include/releases.inc` with the old release info (updates the 254 download archives). 255 256 * You can run `php bin/bumpRelease 7 4` where the first number is the major 257 version, and the second number is the minor version (7.4 in this example). 258 259 * If that fails for any non-trivially fixable reason, you can manually copy 260 the old information to `include/releases.inc`. 261 262 2. Update $data['X.Y'] in `web-php:include/version.inc` 263 (X.Y=major.minor release, e.g. '8.0'): 264 265 * `version` to the full version number (e.g. '8.0.1') 266 * `date` to the release date in `j M Y` format (e.g. '5 Jan 2021') 267 * `tags` array should include `security` if this is a security release 268 * `sha256` array and sub-elements for all SHA256 sums 269 270 3. Create the release file (`releases/x_y_z.php`): 271 272 Optionally use `bin/createReleaseEntry -v x.y.z -r` to create 273 a standard announcement template for this and step 6. 274 Add `--security` for a security release. 275 276 Usually we use the same content as for point 6, but included in php 277 template instead of the release xml. 278 279 Edit the generated files to expand on the base message if needed. 280 281 4. Update `web-qa:include/release-qa.php` and add the next version as an 282 QARELEASE (prepare for next RC). Keep `active => true` until there will be 283 no more QA releases. Setting the release number to 0 is sufficient to 284 remove the old QA release from the available QA releases list. 285 286 5. Update the ChangeLog file for the given major version 287 288 e.g. `ChangeLog-7.php` from the `NEWS` file 289 290 * You may want to try `web-php:bin/news2html` to automate this task. 291 292 * Go over the list and put every element on one line. 293 * Check for `&`, `<` and `>` and escape them if necessary. 294 * Remove all the names at the ends of lines. 295 * For marking up, you can do the following (with `vi`): 296 297 I. `s/^- /<li>/` 298 299 II. `s/$/<\/li>/` 300 301 III. `s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/` 302 303 IV. `s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/` 304 305 V. `s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/` 306 307 6. Add a short notice to `web-php` stating that there is a new release, and 308 highlight the major important things (security fixes) and when it is 309 important to upgrade. 310 311 * Call `php bin/createReleaseEntry -v <version> [ --security ]` in your 312 local web-php checkout. 313 314 7. Commit and push all the changes to their respective git repos 315 316 8. **Check website has been synced before announcing or pushing news** 317 318 Try, e.g. https://www.php.net/distributions/php-7.4.0.tar.xz 319 320 Website may update slowly (may take an hour). 321 322 9. Please note down the sha256 and the PGP signature (.asc). These *must* be 323 included in the release mail. 324 32510. Wait an hour or two, then send a mail to php-announce@lists.php.net, 326 php-general@lists.php.net and internals@lists.php.net with a text similar to 327 http://news.php.net/php.internals/17222. Please make sure that the mail to 328 php-announce@ is its own completely separate email. This is to make sure 329 that replies to the announcement on php-general@ or internals@ will not 330 accidentally hit the php-announce@ mailinglist. 331 33211. Post tweet with release announcement and link to news article on php.net 333 ([@official_php](https://twitter.com/official_php)) 334 335## Re-releasing the same version (or -pl) 336 337 1. Commit the new binaries to `web-php-distributions` 338 339 2. Update $data['X.Y'] in `web-php:/include/version.inc` 340 (X.Y=major.minor release, e.g. '8.0'): 341 342 * `version` to the full version number (e.g. '8.0.1-pl1') 343 * `date` to the release date in `j M Y` format (e.g. '9 Jan 2021') 344 * `tags` array should include `security` if this is a security release 345 * `sha256` array and sub-elements for all SHA256 sums 346 347 3. Add a short notice to `web-php` stating that there is a new release, and 348 highlight the major important things (security fixes) and when it is 349 important to upgrade. 350 351 * Call `php bin/createReleaseEntry -v <version> [ --security ]` in your 352 local web-php checkout. 353 354 4. Commit all the changes (`include/version.inc`, `archive/archive.xml`, 355 `archive/entries/YYYY-MM-DD-N.xml`). 356 357 5. Wait an hour or two, then send a mail to php-announce@lists.php.net, 358 php-general@lists.php.net and internals@lists.php.net with a text similar to 359 the news entry. 360 361 Please make sure that the mail to php-announce@ is its own completely 362 separate email. This is to make sure that replies to the announcement on 363 php-general@ or internals@ will not accidentally hit the php-announce@ 364 mailinglist. 365 366## Forking a new release branch 367 368 1. One week prior to cutting X.Y.0RC1, warn internals@ that your version's 369 branch is about to be cut. Try to be specific about when the branch will 370 be cut. 371 372 Example: http://news.php.net/php.internals/99864 373 374 2. Just prior to cutting X.Y.0RC1, create the new branch locally. 375 376 Add a commit on master after the branch point clearing the `NEWS`, 377 `UPGRADING` and `UPGRADING.INTERNALS` files, updating the version in 378 `configure.ac` (run `./configure` to automatically update 379 `main/php_versions.h`, too) and `Zend/zend.h`. Bump the default initial 380 version also in `win32/build/confutils.js`. 381 382 Also list the new branch in `CONTRIBUTING.md`. 383 384 Bump API version numbers in `Zend/zend_extensions.h`, `Zend/zend_modules.h`, 385 and `main/php.h`. 386 387 Example: 388 https://github.com/php/php-src/commit/a63c99ba624cff86292ffde97089428e68c6fc10 389 390 Push the new branch and the commit just added to master. 391 392 3. Immediately notify internals@ of the branch cut and advise the new merging 393 order. Example: 394 395 http://news.php.net/php.internals/99903 396 397 4. Update `web-php:git.php` and https://wiki.php.net/vcs/gitworkflow to reflect 398 the new branch. Example: 399 400 https://github.com/php/web-php/commit/74bcad4c770d95f21b7fbeeedbd76d943bb83f23 401 402## Preparing for the initial stable version (PHP X.Y.0) 403 404 1. About the time you release the first RC, remind the documentation team 405 (phpdoc@lists.php.net) to write the migration guide. See to it that they 406 have done it before you release the initial stable version, since you want 407 to link to it in the release announcements. 408 409 2. Timely get used to the differences in preparing and announcing a stable 410 release. 411 412 3. Before releasing X.Y.0, merge the NEWS entries of the pre-releases, so that 413 there is only a single section about PHP X.Y.0, instead of individual 414 sections for each pre-release. 415 416## Prime the selection of the Release Managers of the next version 417 418This should be done by one of the release managers of the latest release 419branch: 420 421 1. About three months before the scheduled release of the first alpha of the 422 next minor or major release, issue a call for volunteers on 423 internals@lists.php.net (cf. http://news.php.net/php.internals/98652). 424 425 2. Make sure that there are two or more volunteers, and hold a vote if 426 necessary (see 427 https://wiki.php.net/rfc/releaseprocess#release_managers_selection). 428 429 3. Help the new release managers with their first steps. 430 431## New Release Manager Checklist 432 433 1. Email systems@php.net to get setup for access to downloads.php.net and to be added 434 to the release-managers@ distribution list. 435 436 2. Request membership to the Release Managers group on GitHub. 437 438 3. Create a GPG key for your @php.net address and publish it by editing 439 `include/gpg-keys.inc` in the `web-php` repository, adding the output of 440 `gpg --fingerprint "$USER@php.net"`. Let one or more of the previous RMs 441 sign your key. Publish your public key to pgp.mit.edu with: 442 `gpg --keyserver pgp.mit.edu --send-keys $KEYID` 443 Add new keys in the php-keyring.gpg in distribution repository using: 444 `gpg2 --export --export-options export-minimal --armor <all RM keys>` 445 446 4. Request moderation access to php-announce@lists.php.net and 447 primary-qa-tester@lists.php.net lists, to be able to moderate your release 448 announcements. All the announcements should ideally be sent from the 449 @php.net alias. Note, that for sending emails as @php.net alias a custom 450 SMTP server needs to be used. 451