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 alpha version, bump also API version numbers in 97 `Zend/zend_extensions.h`, `Zend/zend_modules.h`, and `main/php.h`. The API 98 versions between the alpha/beta/.0RCx releases can be left the same or 99 bumped as little as possible because PHP extensions will need to be rebuilt 100 with each bump. 101 102 6. Compile and run `make test`, with and without ZTS, using the right Bison and 103 re2c version (for PHP 7.4, minimum Bison 3.0.0 and re2c 0.13.4 are used). 104 105 7. Check `./sapi/cli/php -v` output for version matching. 106 107 8. If all is right, commit the changes to the release branch: 108 109 ```sh 110 git commit -a 111 ``` 112 113 9. Tag the repository release branch with the version, e.g.: 114 115 ```sh 116 git tag -u YOURKEYID php-7.4.2RC2 117 ``` 118 11910. Bump the version numbers in `main/php_version.h`, `Zend/zend.h`, 120 `configure.ac` and `NEWS` in the *main* branch (PHP-7.4 for example) to 121 prepare for the **next** version. For example, if the RC is "7.4.1RC1" then 122 the new one should be `7.4.2-dev` - regardless if we get a new RC or not. 123 This is to make sure `version_compare()` can correctly work. Commit the 124 changes to the main branch. 125 12611. Push the changes to the main repo, the tag, the main branch and the release 127 branch. Release branches for alpha/beta/.0RCx releases before the GA release 128 don't need to be pushed (a local temporary branch should be used). 129 130 ```sh 131 git push --tags origin HEAD 132 git push origin {main branch} 133 git push origin {release branch} 134 ``` 135 13612. Run: `./scripts/dev/makedist php-7.4.0RC2`, this will export the tree, 137 create `configure` and build three tarballs (gz, bz2 and xz). 138 13913. Run `scripts/dev/gen_verify_stub <version> [identity]`, this will sign the 140 tarballs and output verification information to be included in announcement 141 email. 142 14314. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there 144 should be a directory `public_html/`. Copy them into there. If you do not 145 have this directory, create it. 146 14715. Now the RC can be found on https://downloads.php.net/~yourname, 148 e.g. https://downloads.php.net/~derick/. 149 15016. Once the release has been tagged, contact the release-managers@ distribution 151 list so that Windows binaries can be created. Once those are made, they can 152 be found at https://windows.php.net/download. 153 154## Getting the non stable release (alpha/beta/RC) announced 155 156 1. Update `qa.git/include/release-qa.php` with the appropriate information. See 157 the documentation within release-qa.php for more information, but all 158 releases and RCs are configured here. Only `$QA_RELEASES` needs to be 159 edited. 160 161 Example: When rolling an RC, set the `rc` with appropriate information for 162 the given version. 163 164 Note: Remember to update the sha256 checksum information. 165 166 2. Skip this step for non stable releases after GA of minor or major versions 167 (e.g. announce 7.4.0RC1, but not 7.4.1RC1): 168 169 Add a short notice to phpweb stating that there is a new release, and 170 highlight the major important things (security fixes) and when it is 171 important to upgrade. 172 173 * Call `php bin/createNewsEntry` in your local phpweb checkout. Use category 174 "frontpage" *and* "releases" for all stable releases. Use category 175 "frontpage" for X.Y.0 non-stable releases only (news only). 176 177 * Add the content for the news entry. Be sure to include the text: 178 179 ```text 180 "THIS IS A DEVELOPMENT PREVIEW - DO NOT USE IT IN PRODUCTION!" 181 ``` 182 183 3. Commit and push changes to qa and web. 184 185 Wait for web and qa sites to update with new information before sending 186 announce. 187 188 4. Send **separate** emails **To** `internals@lists.php.net` and 189 `php-general@lists.php.net` lists pointing out "the location of the release" 190 and "the possible release date of either the next RC, or the final release". 191 Include in this information the verification information output by 192 `gen_verify_stub`. 193 194 5. Send **separate** emails (see example http://news.php.net/php.pear.qa/5201) 195 **To** `php-qa@lists.php.net` and `primary-qa-tester@lists.php.net`. These 196 emails are to notify the selected projects about a new release so that they 197 can make sure their projects keep working. Make sure that you have been 198 setup as a moderator for `primary-qa-tester@lists.php.net` by having someone 199 (Hannes, Dan, Derick) run the following commands for you: 200 201 ```sh 202 ssh lists.php.net 203 sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address 204 ``` 205 206## Rolling a stable release 207 208 1. Checkout your release branch, you should have created when releasing 209 previous RC and bump the version numbers in `main/php_version.h`, 210 `Zend/zend.h`, `configure.ac` and possibly `NEWS`. 211 212 2. If a CVE commit needs to be merged to the release, then have it committed to 213 the base branches and merged upwards as usual (e.g. commit the CVE fix to 214 7.2, merge to 7.3, 7.4 etc...). Then you can cherry-pick it in your release 215 branch. Don't forget to update `NEWS` manually in an extra commit then. 216 217 3. Commit those changes. Ensure the tests at 218 https://travis-ci.org/php/php-src/builds are still passing. 219 220 4. Run the `scripts/dev/credits` script in php-src and commit the changes in 221 the credits files in ext/standard. 222 223 5. Compile and run `make test`, with and without ZTS, using the right Bison and 224 re2c version (for PHP 7.4, minimum Bison 3.0.0 and re2c 0.13.4 are used). 225 226 6. Check `./sapi/cli/php -v` output for version matching. 227 228 7. Tag the repository with the version e.g. `git tag -u YOURKEYID php-7.4.1` 229 230 8. Push the tag e.g. `git push origin php-7.4.1`. 231 232 9. Run: `./scripts/dev/makedist php-7.4.1`, this will export the tag, 233 create configure and build three tarballs (gz, bz2 and xz). Check if the 234 pear files are updated (phar). On some systems the behavior of GNU tar can 235 default to produce POSIX compliant archives with PAX headers. As not every 236 application is compatible with that format, creation of archives with PAX 237 headers should be avoided. When packaging on such a system, the GNU tar can 238 be influenced by defining the environment variable 239 `TAR_OPTIONS='--format=gnu'`. 240 24110. Run `scripts/dev/gen_verify_stub <version> [identity]`, this will sign the 242 tarballs and output verification information to be included in announcement 243 email. 244 24511. Commit and push all the tarballs and signature files to 246 `web/php-distributions.git`, then update the git submodule reference in 247 `web/php.git`: 248 249 ```sh 250 git submodule init 251 git submodule update 252 cd distributions 253 git fetch 254 git pull --rebase origin master 255 cd .. 256 git commit distributions 257 git push 258 ``` 259 260 This is to fetch the last commit id from php-distributions.git and commit 261 this last commit id to `web/php.git`, then, website will now sync. 262 26312. Once the release has been tagged, contact release managers, Windows 264 builders, and package maintainers so that they can build releases. Do not 265 send this announcement to any public lists. 266 267## Getting the stable release announced 268 269 1. Update `phpweb/include/releases.inc` with the old release info (updates the 270 download archives). 271 272 * You can run `php bin/bumpRelease 7 4` where the first number is the major 273 version, and the second number is the minor version (7.4 in this example). 274 275 * If that fails for any non-trivially fixable reason, you can manually copy 276 the old information to `include/releases.inc`. 277 278 2. Update `phpweb/include/version.inc` (X_Y=major_minor release number): 279 280 * `$PHP_X_Y_VERSION` to the correct version 281 * `$PHP_X_Y_DATE` to the release date 282 * `$PHP_X_Y_SHA256` array and update all the SHA256 sums 283 * `$PHP_X_Y_TAGS` array should include `security` if this is a security 284 release 285 * Make sure there are no outdated "notes" or edited "date" keys in the 286 `$RELEASES[X][$PHP_X_VERSION]["source"]` array. 287 288 3. Create the release file (`releases/x_y_z.php`) 289 290 Usually we use the same content as for point 6, but included in php template 291 instead of the release xml. 292 293 4. Update `php-qa/include/release-qa.php` and add the next version as an 294 QARELEASE (prepare for next RC). 295 296 5. Update the ChangeLog file for the given major version 297 298 e.g. `ChangeLog-7.php` from the `NEWS` file 299 300 * You may want to try `php-web/bin/news2html` to automate this task. 301 302 * Go over the list and put every element on one line. 303 * Check for `&`, `<` and `>` and escape them if necessary. 304 * Remove all the names at the ends of lines. 305 * For marking up, you can do the following (with `vi`): 306 307 I. `s/^- /<li>/` 308 309 II. `s/$/<\/li>/` 310 311 III. `s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/` 312 313 IV. `s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/` 314 315 V. `s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/` 316 317 6. Add a short notice to phpweb stating that there is a new release, and 318 highlight the major important things (security fixes) and when it is 319 important to upgrade. 320 321 * Call `php bin/createNewsEntry` in your local phpweb checkout. 322 * Use the "frontpage" and "releases" category. 323 * Add the content for the news entry. 324 325 7. Commit and push all the changes to their respective git repos 326 327 8. **Check website has been synced before announcing or pushing news** 328 329 Try, e.g. https://www.php.net/distributions/php-7.4.0.tar.xz 330 331 Website may update slowly (may take an hour). 332 333 9. Please note down the sha256 and the PGP signature (.asc). These *must* be 334 included in the release mail. 335 33610. Wait an hour or two, then send a mail to php-announce@lists.php.net, 337 php-general@lists.php.net and internals@lists.php.net with a text similar to 338 http://news.php.net/php.internals/17222. Please make sure that the mail to 339 php-announce@ is its own completely separate email. This is to make sure 340 that replies to the announcement on php-general@ or internals@ will not 341 accidentally hit the php-announce@ mailinglist. 342 343## Re-releasing the same version (or -pl) 344 345 1. Commit the new binaries to `phpweb/distributions/` 346 347 2. Update `phpweb/include/version.inc` (X_Y=major_minor release number): 348 349 * If only releasing for one OS, make sure you edit only those variables. 350 * `$PHP_X_Y_VERSION` to the correct version 351 * `$PHP_X_Y_DATE` to the release date 352 * `$PHP_X_Y_SHA256` array and update all the SHA256 sums 353 * Make sure there are no outdated "notes" or edited "date" keys in the 354 `$RELEASES[X][$PHP_X_VERSION]["source"]` array. 355 356 3. Add a short notice to phpweb stating that there is a new release, and 357 highlight the major important things (security fixes) and when it is 358 important to upgrade. 359 360 * Call `php bin/createNewsEntry` in your local phpweb checkout. 361 * Add the content for the news entry. 362 363 4. Commit all the changes (`include/version.inc`, `archive/archive.xml`, 364 `archive/entries/YYYY-MM-DD-N.xml`). 365 366 5. Wait an hour or two, then send a mail to php-announce@lists.php.net, 367 php-general@lists.php.net and internals@lists.php.net with a text similar to 368 the news entry. 369 370 Please make sure that the mail to php-announce@ is its own completely 371 separate email. This is to make sure that replies to the announcement on 372 php-general@ or internals@ will not accidentally hit the php-announce@ 373 mailinglist. 374 375## Forking a new release branch 376 377 1. One week prior to cutting X.Y.0beta1, warn internals@ that your version's 378 branch is about to be cut, and that PHP-X.Y will be moving into feature 379 freeze. Try to be specific about when the branch will be cut. 380 381 Example: http://news.php.net/php.internals/99864 382 383 2. Just prior to cutting X.Y.0beta1, create the new branch locally. 384 385 Add a commit on master after the branch point clearing the `NEWS`, 386 `UPGRADING` and `UPGRADING.INTERNALS` files, updating the version in 387 `configure.ac` (run `./configure` to automatically update 388 `main/php_versions.h`, too) and `Zend/zend.h`. Bump the default initial 389 version also in `win32/build/confutils.js`. 390 391 Also list the new branch in `CONTRIBUTING.md`. 392 393 Bump API version numbers in `Zend/zend_extensions.h`, `Zend/zend_modules.h`, 394 and `main/php.h`. 395 396 Example: https://git.php.net/?p=php-src.git;a=commit;h=a63c99b 397 Push the new branch and the commit just added to master. 398 399 3. Immediately notify internals@ of the branch cut and advise the new merging 400 order. Example: 401 402 http://news.php.net/php.internals/99903 403 404 4. Update php-web:git.php and https://wiki.php.net/vcs/gitworkflow to reflect 405 the new branch. Example: 406 407 https://github.com/php/web-php/commit/74bcad4c770d95f21b7fbeeedbd76d943bb83f23 408 409 5. Notify nlopess@ to add PHP_X_Y tag to gcov.php.net. 410 411## Preparing for the initial stable version (PHP X.Y.0) 412 413 1. About the time you release the first RC, remind the documentation team 414 (phpdoc@lists.php.net) to write the migration guide. See to it that they 415 have done it before you release the initial stable version, since you want 416 to link to it in the release announcements. 417 418 2. Timely get used to the differences in preparing and announcing a stable 419 release. 420 421## Prime the selection of the Release Managers of the next version 422 423 1. About three months before the scheduled release of the first alpha of the 424 next minor or major release, issue a call for volunteers on 425 internals@lists.php.net (cf. http://news.php.net/php.internals/98652). 426 427 2. Make sure that there are two or more volunteers, and hold a vote if 428 necessary (see 429 https://wiki.php.net/rfc/releaseprocess#release_managers_selection). 430 431 3. Help the new release managers with their first steps. 432 433## New Release Manager checklist 434 435 1. Email systems@ to get setup for access to downloads.php.net and to be added 436 to the release-managers@ distribution list. 437 438 2. 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 444 3. Request karma to edit `main/php_version.h` and `Zend/zend.h`. Possibly karma 445 for other restricted parts of php-src might come in question. To edit 446 `main/php_version.h` in a release branch, you need release manager karma in 447 `global_avail`. 448 449 4. Request karma for `web/qa.git` and `web/php.git` for publishing release 450 announcements. 451 452 5. Request moderation access to php-announce@lists.php.net and 453 primary-qa-tester@lists.php.net lists, to be able to moderate your release 454 announcements. All the announcements should ideally be sent from the 455 @php.net alias. Note, that for sending emails as @php.net alias a custom 456 SMTP server needs to be used. 457