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 an 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 tone 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.in`` 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.in`` 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 "downloads/". Copy them into there, so that the system can generate 101MD5 sums. If you do not have this directory, talk to Derick or Dan. 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 PHP Windows development team 107(internals-win@lists.php.net) so that Windows binaries can be created. Once 108those are made, they should be placed into the same directory as the source snapshots. 109 110Getting the non stable release (alpha/beta/RC) announced 111-------------------------------------------------------- 112 1131. Send an email **To** ``internals@lists.php.net`` and ``php-general@lists.php.net`` 114lists pointing out "the location of the release" and "the possible release date of 115either the next RC, or the final release". Include in this information the verification 116information output by ``gen_verify_stub``. 117 1182. Send an email (see example here http://news.php.net/php.pear.qa/5201) **To** 119``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``. 120This email is to notify the selected projects about a new release so that they 121can make sure their projects keep working. Make sure that you have been setup 122as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan, 123Derick) run the following commands for you: 124 125``ssh lists.php.net`` 126 127``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address`` 128 1293. Update ``qa.git/include/release-qa.php`` with the appropriate information. 130 See the documentation within release-qa.php for more information, but all releases 131 and RCs are configured here. Only $QA_RELEASES needs to be edited. 132 133 Example: When rolling an RC, set the 'rc' with appropriate information for the 134 given version. 135 136 Note: Remember to update the MD5 checksum information. 137 1384. Update ``web/php.git/include/version.inc`` (x=major version number) 139 140 a. ``$PHP_x_RC`` = "5.4.0RC1" (should be set to "false" before) 141 142 b. ``$PHP_x_RC_DATE`` = "06 September 2007" 143 1445. Commit and push those changes: 145 146 a. ``git commit -a && git push origin master`` 147 1486. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the 149INSTALL and win32/install.txt files which are generated from the PHP manual sources. 150 151Rolling a stable release 152------------------------ 153 1541. Checkout your release branch, you should have created when releasing previous RC 155and bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``. 156 1572. If a CVE commit needs to be merged to the release, then have it committed to 158the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3, 159merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch. 160Don't forget to update NEWS manually in an extra commit then. 161 1623. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are 163still passing. 164 1654. run the "scripts/dev/credits" script in php-src and commit the changes in the 166credits files in ext/standard. 167 1685. Compile and make test, with and without ZTS, using the right Bison version 169(for example, for 5.5, Bison 2.4.1 is used) 170 1716. Check ./sapi/cli/php -v output for version matching. 172 1737. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``" 174 1758. Push the tag f.e. "``git push origin php-5.4.1``" 176 1779. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure 178and build three tarballs (gz, bz2 and xz). 179Check if the pear files are updated (phar). 180 18110. Generate the GPG signature files for the archives. 182 ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx`` 183 18411. Commit and push all the tarballs and signature files to web/php-distributions.git, 185 then update the git submodule reference in web/php.git: 186 ``git submodule init; 187 git submodule update; 188 cd distributions; 189 git pull origin master; 190 cd ..; 191 git commit distributions; 192 git push;`` 193This is to fetch the last commit id from php-distributions.git and commit this 194last commit id to web/php.git, then, mirrors will now sync 195 19612. Once the release has been tagged, contact release managers, windows builders, and package maintainers 197so that they can build releases. Do not send this announcement to any public lists. 198 199Getting the stable release announced 200------------------------------------ 201 2021. Update phpweb/include/releases.inc with the old release info 203 (updates the download archives) 204 205 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the 206 highest branch, otherwise you have to do this manually, see point 1.b 207 208 b. In case multiple PHP minor versions are in active development you have 209 to manually copy the old information to include/releases.inc 210 2112. Edit ``phpweb/include/version.inc`` and change (X=major release number): 212 213 a. ``$PHP_X_VERSION`` to the correct version 214 215 b. ``$PHP_X_DATE`` to the release date 216 217 c. ``$PHP_X_MD5`` array and update all the md5 sums 218 219 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums 220 221 e. set ``$PHP_X_RC`` to false! 222 223 f. Make sure there are no outdated "notes" or edited "date" keys in the 224 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array 225 226 g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows") 227 2283. Create the release file (releases/x_y_z.php) 229 Usually we use the same content as for point 6, but included in php template 230 instead of the release xml. 231 2324. Update php-qa/include/release-qa.php and add the next version as an QARELEASE 233 (prepare for next RC) 234 2355. Update the ChangeLog file for the given major version 236f.e. ``ChangeLog-5.php`` from the NEWS file 237 238 a. go over the list and put every element on one line 239 240 b. check for &, < and > and escape them if necessary 241 242 c. remove all the names at the ends of lines 243 244 d. for marking up, you can do the following (with VI): 245 246 I. ``s/^- /<li>/`` 247 248 II. ``s/$/<\/li>/`` 249 250 III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/`` 251 252 IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/`` 253 254 V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/`` 255 256 e. You may want to try php-web/bin/news2html to automate this task 257 2586. Add a short notice to phpweb stating that there is a new release, and 259highlight the major important things (security fixes) and when it is important 260to upgrade. 261 262 a. Call php bin/createNewsEntry in your local phpweb checkout 263 264 b. Add the content for the news entry 265 2667. **Check mirrors have been synced before announcing or pushing news** 267 Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror 268 Try several mirrors, mirrors may update slowly (may take an hour) 269 2708. Commit all the changes to their respective git repos 271 2729. Please note down the sha256 and the PGP signature (.asc). These *must* be 273 included in the release mail. 27410. Wait an hour or two, then send a mail to php-announce@lists.php.net, 275php-general@lists.php.net and internals@lists.php.net with a text similar to 276http://news.php.net/php.internals/17222. 277Please make sure that the mail to php-announce@ is its own completely separate email. 278This is to make sure that replies to the announcement on php-general@ or internals@ 279will not accidentally hit the php-announce@ mailinglist. 280 281Re-releasing the same version (or -pl) 282-------------------------------------- 283 2841. Commit the new binaries to ``phpweb/distributions/`` 285 2862. Edit ``phpweb/include/version.inc`` and change (X=major release number): 287 288 a. If only releasing for one OS, make sure you edit only those variables 289 290 b. ``$PHP_X_VERSION`` to the correct version 291 292 c. ``$PHP_X_DATE`` to the release date 293 294 d. ``$PHP_X_MD5`` array and update all the md5 sums 295 296 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums 297 298 f. Make sure there are no outdated "notes" or edited "date" keys in the 299 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array 300 3013. Add a short notice to phpweb stating that there is a new release, and 302highlight the major important things (security fixes) and when it is important 303to upgrade. 304 305 a. Call php bin/createNewsEntry in your local phpweb checkout 306 307 b. Add the content for the news entry 308 3094. Commit all the changes (``include/version.inc``, ``archive/archive.xml``, 310``archive/entries/YYYY-MM-DD-N.xml``) 311 3125. Wait an hour or two, then send a mail to php-announce@lists.php.net, 313php-general@lists.php.net and internals@lists.php.net with a text similar to 314the news entry. 315Please make sure that the mail to php-announce@ is its own completely separate email. 316This is to make sure that replies to the announcement on php-general@ or internals@ 317will not accidentally hit the php-announce@ mailinglist. 318
