1======================= 2 PHP Release Process 3======================= 4 5General notes and tips 6---------------------- 7 81. Do not release on Fridays, Saturdays or Sundays 9because the sysadmins can not upgrade stuff then. 10 112. Package two days before a release. So if the release is to be on Thursday, 12package on Tuesday. Think about timezones as well. 13 143. Ensure that the tests on Travis CI are green. 15See: https://travis-ci.org/php/php-src/builds 16It is recommended to do so a couple of days before the packaging day, to 17have enough time to investigate failures, communicate with the authors and 18commit the fixes. 19The RM for the branch is also responsible for keeping the CI green on 20ongoing basis between the releases. Check the CI status for your branch 21periodically and resolve the failures ASAP. See more in: 22https://wiki.php.net/rfc/travis_ci 23 244. Ensure that Windows builds will work before packaging 25 265. Follow all steps to the letter. When unclear ask previous RM's (David/Julien/ 27Johannes/Stas/Derick/Ilia) before proceeding. Ideally make sure that for the 28first releases one of the previous RM's is around to answer questions. For the 29steps related to the php/QA/bug websites try to have someone from the webmaster 30team (Bjori) on hand. 31 326. Verify the tags to be extra sure everything was tagged properly. 33 347. Moving extensions from/to PECL requires write access to the destination. 35Most developers should have this. 36 37Moving extensions from php-src to PECL 38- Checkout the pecl directory, most likely you want a sparse-root checkout 39 svn co --depth=empty https://svn.php.net/repository/pecl 40- Create a directory for the extension incl. branch and tag structure, 41 no trunk at this point and commit this to svn 42 cd pecl; mkdir foo foo/tags foo/branches; svn add foo; svn commit 43- Move the extension from php-src to the new location 44 svn mv https://svn.php.net/repository/php/php-src/trunk/ext/foo \ 45 https://svn.php.net/repository/pecl/foo/trunk 46 47If the extension is still usable or not dead, in cooperation with the extension 48maintainers if any: 49- create the pecl.php.net/foo package and its content, license, maintainer 50- create the package.xml, commit 51- release the package 52 53For Moving extensions from PECL to php-src the svn mv has to be done the other 54way round. 55 56Rolling a non stable release (alpha/beta/RC) 57-------------------------------------------- 58 591. Check windows snapshot builder logs (http://windows.php.net/downloads/snaps/ the last revision) 60 612. Check the tests at https://travis-ci.org/php/php-src/builds 62 633. run the "scripts/dev/credits" script in php-src and commit the changes in the 64credits files in ext/standard. 65 664. Checkout the release branch for this release (e.g., PHP-5.4.2) from the main branch. 67 685. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``. 69Do not use abbreviations for alpha and beta. Do not use dashes, you should 70``#define PHP_VERSION "5.4.22RC1"`` and not ``#define PHP_VERSION "5.4.22-RC1"`` 71 726. Compile and make test, with and without ZTS, using the right Bison version 73(for example, for 5.5, Bison 2.4.1 is used) 74 757. Check ./sapi/cli/php -v output for version matching. 76 778. If all is right, commit the changes to the release branch with ``git commit -a``. 78 799. Tag the repository release branch with the version, e.g.: 80``git tag -u YOURKEYID php-5.4.2RC2`` 81 8210. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and ``NEWS`` 83in the *main* branch (PHP-5.4 for example) to prepare for the **next** version. 84F.e. if the RC is "5.4.1RC1" then the new one should be "5.4.2-dev" - regardless if we get 85a new RC or not. This is to make sure ``version_compare()`` can correctly work. 86Commit the changes to the main branch. 87 8811. Push the changes to the main repo, the tag, the main branch and the release branch : 89``git push --tags origin HEAD`` 90``git push origin {main branch}`` 91``git push origin {release branch}`` 92 9312. run: ``PHPROOT=. ./makedist 5.4.2RC2``, this will export the tree, create configure 94and build three tarballs (gz, bz2 and xz). 95 9613. run ``scripts/dev/gen_verify_stub <version> [identity]``, this will sign the tarballs 97and output verification information to be included in announcement email 98 9914. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a 100directory "public_html/". Copy them into there, so that the system can generate 101MD5 sums. If you do not have this directory, create it. 102 10315. Now the RC can be found on http://downloads.php.net/~yourname, 104f.e. http://downloads.php.net/~derick/ 105 10616. Once the release has been tagged, contact the release-managers@ distribution list 107so that Windows binaries can be created. Once those are made, they can be found at 108http://windows.php.net/download 109 110Getting the non stable release (alpha/beta/RC) announced 111-------------------------------------------------------- 112 1131. Update ``qa.git/include/release-qa.php`` with the appropriate information. 114 See the documentation within release-qa.php for more information, but all releases 115 and RCs are configured here. Only $QA_RELEASES needs to be edited. 116 117 Example: When rolling an RC, set the 'rc' with appropriate information for the 118 given version. 119 120 Note: Remember to update the MD5 and sha256 checksum information. 121 1222. Update ``web/php.git/include/version.inc`` (x=major version number) 123 124 a. ``$PHP_x_RC`` = "5.4.0RC1" (should be set to "false" before) 125 126 b. ``$PHP_x_RC_DATE`` = "06 September 2007" 127 1283. Add a short notice to phpweb stating that there is a new release, and 129highlight the major important things (security fixes) and when it is important 130to upgrade. 131 132 a. Call php bin/createNewsEntry in your local phpweb checkout 133 Use category "releases" for all stable releases. 134 Use category "frontpage" for X.Y.0 non-stable releases only (news only). 135 136 b. Add the content for the news entry. Be sure to include the text: 137 "THIS IS A DEVELOPMENT PREVIEW - DO NOT USE IT IN PRODUCTION!" 138 1394. Commit and push changes to qa and web 140 141*Wait for web and qa sites to update with new information before sending announce* 142 1435. Send **separate** emails **To** ``internals@lists.php.net`` and ``php-general@lists.php.net`` 144lists pointing out "the location of the release" and "the possible release date of 145either the next RC, or the final release". Include in this information the verification 146information output by ``gen_verify_stub``. 147 1486. Send **separate** emails (see example here http://news.php.net/php.pear.qa/5201) **To** 149``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``. 150These emails are to notify the selected projects about a new release so that they 151can make sure their projects keep working. Make sure that you have been setup 152as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan, 153Derick) run the following commands for you: 154 155``ssh lists.php.net`` 156 157``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address`` 158 159Rolling a stable release 160------------------------ 161 1621. Checkout your release branch, you should have created when releasing previous RC 163and bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``. 164 1652. If a CVE commit needs to be merged to the release, then have it committed to 166the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3, 167merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch. 168Don't forget to update NEWS manually in an extra commit then. 169 1703. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are 171still passing. 172 1734. run the "scripts/dev/credits" script in php-src and commit the changes in the 174credits files in ext/standard. 175 1765. Compile and make test, with and without ZTS, using the right Bison version 177(for example, for 5.5, Bison 2.4.1 is used) 178 1796. Check ./sapi/cli/php -v output for version matching. 180 1817. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``" 182 1838. Push the tag f.e. "``git push origin php-5.4.1``" 184 1859. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure 186and build three tarballs (gz, bz2 and xz). 187 Check if the pear files are updated (phar). 188 On some systems the behavior of GNU tar can default to produce POSIX compliant archives 189with PAX headers. As not every application is compatible with that format, creation of 190archives with PAX headers should be avoided. When packaging on such a system, the GNU tar 191can be influenced by defining the environment variable TAR_OPTIONS='--format=gnu'. 192 19310. Generate the GPG signature files for the archives. 194 ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx`` 195 19611. Commit and push all the tarballs and signature files to web/php-distributions.git, 197 then update the git submodule reference in web/php.git: 198 ``git submodule init; 199 git submodule update; 200 cd distributions; 201 git fetch; 202 git pull --rebase origin master; 203 cd ..; 204 git commit distributions; 205 git push;`` 206This is to fetch the last commit id from php-distributions.git and commit this 207last commit id to web/php.git, then, mirrors will now sync 208 20912. Once the release has been tagged, contact release managers, windows builders, and package maintainers 210so that they can build releases. Do not send this announcement to any public lists. 211 212Getting the stable release announced 213------------------------------------ 214 2151. Update phpweb/include/releases.inc with the old release info 216 (updates the download archives) 217 218 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the 219 highest branch, otherwise you have to do this manually, see point 1.b 220 221 b. In case multiple PHP minor versions are in active development you have 222 to manually copy the old information to include/releases.inc 223 2242. Edit ``phpweb/include/version.inc`` and change (X=major release number): 225 226 a. ``$PHP_X_VERSION`` to the correct version 227 228 b. ``$PHP_X_DATE`` to the release date 229 230 c. ``$PHP_X_MD5`` array and update all the md5 sums 231 232 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums 233 234 e. set ``$PHP_X_RC`` to false! 235 236 f. Make sure there are no outdated "notes" or edited "date" keys in the 237 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array 238 239 g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows") 240 2413. Create the release file (releases/x_y_z.php) 242 Usually we use the same content as for point 6, but included in php template 243 instead of the release xml. 244 2454. Update php-qa/include/release-qa.php and add the next version as an QARELEASE 246 (prepare for next RC) 247 2485. Update the ChangeLog file for the given major version 249f.e. ``ChangeLog-5.php`` from the NEWS file 250 251 a. go over the list and put every element on one line 252 253 b. check for &, < and > and escape them if necessary 254 255 c. remove all the names at the ends of lines 256 257 d. for marking up, you can do the following (with VI): 258 259 I. ``s/^- /<li>/`` 260 261 II. ``s/$/<\/li>/`` 262 263 III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/`` 264 265 IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/`` 266 267 V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/`` 268 269 e. You may want to try php-web/bin/news2html to automate this task 270 2716. Add a short notice to phpweb stating that there is a new release, and 272highlight the major important things (security fixes) and when it is important 273to upgrade. 274 275 a. Call php bin/createNewsEntry in your local phpweb checkout 276 277 b. Add the content for the news entry 278 2797. **Check mirrors have been synced before announcing or pushing news** 280 Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror 281 Try several mirrors, mirrors may update slowly (may take an hour) 282 2838. Commit all the changes to their respective git repos 284 2859. Please note down the sha256 and the PGP signature (.asc). These *must* be 286 included in the release mail. 28710. Wait an hour or two, then send a mail to php-announce@lists.php.net, 288php-general@lists.php.net and internals@lists.php.net with a text similar to 289http://news.php.net/php.internals/17222. 290Please make sure that the mail to php-announce@ is its own completely separate email. 291This is to make sure that replies to the announcement on php-general@ or internals@ 292will not accidentally hit the php-announce@ mailinglist. 293 294Re-releasing the same version (or -pl) 295-------------------------------------- 296 2971. Commit the new binaries to ``phpweb/distributions/`` 298 2992. Edit ``phpweb/include/version.inc`` and change (X=major release number): 300 301 a. If only releasing for one OS, make sure you edit only those variables 302 303 b. ``$PHP_X_VERSION`` to the correct version 304 305 c. ``$PHP_X_DATE`` to the release date 306 307 d. ``$PHP_X_MD5`` array and update all the md5 sums 308 309 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums 310 311 f. Make sure there are no outdated "notes" or edited "date" keys in the 312 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array 313 3143. Add a short notice to phpweb stating that there is a new release, and 315highlight the major important things (security fixes) and when it is important 316to upgrade. 317 318 a. Call php bin/createNewsEntry in your local phpweb checkout 319 320 b. Add the content for the news entry 321 3224. Commit all the changes (``include/version.inc``, ``archive/archive.xml``, 323``archive/entries/YYYY-MM-DD-N.xml``) 324 3255. Wait an hour or two, then send a mail to php-announce@lists.php.net, 326php-general@lists.php.net and internals@lists.php.net with a text similar to 327the news entry. 328Please make sure that the mail to php-announce@ is its own completely separate email. 329This is to make sure that replies to the announcement on php-general@ or internals@ 330will not accidentally hit the php-announce@ mailinglist. 331 332Forking a new release branch 333---------------------------- 334 3351. One week prior to cutting X.Y.0beta1, warn internals@ that your version's branch 336 is about to be cut, and that PHP-X.Y will be moving into feature freeze. 337 Try to be specific about when the branch will be cut. 338 Example: http://news.php.net/php.internals/99864 339 3402. Just prior to cutting X.Y.0beta1, create the new branch locally. 341 Add a commit on master after the branch point clearing the NEWS file, and updating 342 main/php_versions.h and Zend/zend.h to update versions. 343 Example: https://github.com/php/php-src/commit/5230541ef59e0637d5522293a7d099bf18ce6af3 344 Push the new branch and the commit just added to master. 345 3463. Immediately notify internals@ of the branch cut and advise the new merging order: 347 Example: http://news.php.net/php.internals/99903 348 3494. Update php-web:git.php and wiki.php.net/vcs/gitworkflow to reflect the new branch: 350 Example: https://github.com/php/web-php/commit/74bcad4c770d95f21b7fbeeedbd76d943bb83f23 351 3525. Notify nlopess@ to add PHP_X_Y tag to gcov.php.net 353 354New Release Manager Checklist 355----------------------------- 356 3571. Email systems@ to get setup for access to downloads.php.net and to be added to the 358 release-managers@ distribution list. 359 3602. Create a GPG key for your @php.net address and publish it by editing `include/gpg-keys.inc` 361 in the `web-php` repository, adding the output of `gpg --fingerprint "$USER@php.net"`. Let 362 one or more of the previous RMs sign your key. Publish your public key to pgp.mit.edu with: 363 `gpg --keyserver pgp.mit.edu --send-keys $KEYID` 364 3653. Request karma to edit main/php_version.h. Possibly karma for other restricted parts of 366 php-src might come in question. 367 3684. Request karma for web/qa.git and web/php.git for publishing release announcements. 369 3705. Request moderation access to announce@php.net and primary-qa-tester@lists.php.net lists, to 371 be able to moderate your release announcements. All the announcements should be sent from 372 the @php.net alias. 373
