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