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 bases 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 acces 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. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a 97directory "downloads/". Copy them into there, so that the system can generate 98MD5 sums. If you do not have this directory, talk to Derick or Dan. 99 10014. Now the RC can be found on http://downloads.php.net/yourname, 101f.e. http://downloads.php.net/derick/ 102 10315. Once the release has been tagged, contact the PHP Windows development team 104(internals-win@lists.php.net) so that Windows binaries can be created. Once 105those are made, they should be placed into the same directory as the source snapshots. 106 107Getting the non stable release (alpha/beta/RC) announced 108-------------------------------------------------------- 109 1101. Send an email (see example here: http://news.php.net/php.internals/19486) 111**To** ``internals@lists.php.net`` and ``php-general@lists.php.net`` lists 112pointing out "the location of the release" and "the possible release date of 113either the next RC, or the final release". 114 1152. Send an email (see example here http://news.php.net/php.pear.qa/5201) **To** 116``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``. 117This email is to notify the selected projects about a new release so that they 118can make sure their projects keep working. Make sure that you have been setup 119as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan, 120Derick) run the following commands for you: 121 122``ssh lists.php.net`` 123 124``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address`` 125 1263. Update ``qa.git/include/release-qa.php`` with the appropriate information. 127 See the documentation within release-qa.php for more information, but all releases 128 and RCs are configured here. Only $QA_RELEASES needs to be edited. 129 130 Example: When rolling an RC, set the 'rc' with appropriate information for the 131 given version. 132 133 Note: Remember to update the MD5 checksum information. 134 1354. Update ``web/php.git/include/version.inc`` (x=major version number) 136 137 a. ``$PHP_x_RC`` = "5.4.0RC1" (should be set to "false" before) 138 139 b. ``$PHP_x_RC_DATE`` = "06 September 2007" 140 1415. Commit and push those changes: 142 143 a. ``git commit -a && git push origin master`` 144 1456. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the 146INSTALL and win32/install.txt files which are generated from the PHP manual sources. 147 148Rolling a stable release 149------------------------ 150 1511. Checkout your release branch, you should have created when releasing previous RC 152and bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``. 153 1542. If a CVE commit needs to be merged to the release, then have it committed to 155the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3, 156merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch. 157Don't forget to update NEWS manually in an extra commit then. 158 1593. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are 160still passing. 161 1624. run the "scripts/dev/credits" script in php-src and commit the changes in the 163credits files in ext/standard. 164 1655. Compile and make test, with and without ZTS, using the right Bison version 166(for example, for 5.5, Bison 2.4.1 is used) 167 1686. Check ./sapi/cli/php -v output for version matching. 169 1707. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``" 171 1728. Push the tag f.e. "``git push origin php-5.4.1``" 173 1749. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure 175and build three tarballs (gz, bz2 and xz). 176Check if the pear files are updated (phar). 177 17810. Generate the GPG signature files for the archives. 179 ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx`` 180 18111. Commit and push all the tarballs and signature files to web/php-distributions.git, 182 then update the git submodule reference in web/php.git: 183 ``git submodule init; 184 git submodule update; 185 cd distributions; 186 git pull origin master; 187 cd ..; 188 git commit distributions; 189 git push;`` 190This is to fetch the last commit id from php-distributions.git and commit this 191last commit id to web/php.git, then, mirrors will now sync 192 19312. Once the release has been tagged, contact the PHP Windows development team 194(internals-win@lists.php.net) so that Windows binaries can be created. 195 196Getting the stable release announced 197------------------------------------ 198 1991. Update phpweb/include/releases.inc with the old release info 200 (updates the download archives) 201 202 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the 203 highest branch, otherwise you have to do this manually, see point 1.b 204 205 b. In case multiple PHP minor versions are in active development you have 206 to manually copy the old information to include/releases.inc 207 2082. Edit ``phpweb/include/version.inc`` and change (X=major release number): 209 210 a. ``$PHP_X_VERSION`` to the correct version 211 212 b. ``$PHP_X_DATE`` to the release date 213 214 c. ``$PHP_X_MD5`` array and update all the md5 sums 215 216 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums 217 218 e. set ``$PHP_X_RC`` to false! 219 220 f. Make sure there are no outdated "notes" or edited "date" keys in the 221 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array 222 223 g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows") 224 2253. Create the release file (releases/x_y_z.php) 226 Usually we use the same content as for point 6, but included in php template 227 instead of the release xml. 228 2294. Update php-qa/include/release-qa.php and add the next version as an QARELEASE 230 (prepare for next RC) 231 2325. Update the ChangeLog file for the given major version 233f.e. ``ChangeLog-5.php`` from the NEWS file 234 235 a. go over the list and put every element on one line 236 237 b. check for &, < and > and escape them if necessary 238 239 c. remove all the names at the ends of lines 240 241 d. for marking up, you can do the following (with VI): 242 243 I. ``s/^- /<li>/`` 244 245 II. ``s/$/<\/li>/`` 246 247 III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/`` 248 249 IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/`` 250 251 V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/`` 252 253 e. You may want to try php-web/bin/news2html to automate this task 254 2556. Add a short notice to phpweb stating that there is a new release, and 256highlight the major important things (security fixes) and when it is important 257to upgrade. 258 259 a. Call php bin/createNewsEntry in your local phpweb checkout 260 261 b. Add the content for the news entry 262 2637. **Check mirrors have been synced before announcing or pushing news** 264 Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror 265 Try several mirrors, mirrors may update slowly (may take an hour) 266 2678. Commit all the changes to their respective git repos 268 2699. Wait an hour or two, then send a mail to php-announce@lists.php.net, 270php-general@lists.php.net and internals@lists.php.net with a text similar to 271http://news.php.net/php.internals/17222. 272Please make sure that the mail to php-announce@ is its own completely seperate email. 273This is to make sure that repiles to the announcement on php-general@ or internals@ 274will not accidentally hit the php-announce@ mailinglist. 275 276Re-releasing the same version (or -pl) 277-------------------------------------- 278 2791. Commit the new binaries to ``phpweb/distributions/`` 280 2812. Edit ``phpweb/include/version.inc`` and change (X=major release number): 282 283 a. If only releasing for one OS, make sure you edit only those variables 284 285 b. ``$PHP_X_VERSION`` to the correct version 286 287 c. ``$PHP_X_DATE`` to the release date 288 289 d. ``$PHP_X_MD5`` array and update all the md5 sums 290 291 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums 292 293 f. Make sure there are no outdated "notes" or edited "date" keys in the 294 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array 295 2963. Add a short notice to phpweb stating that there is a new release, and 297highlight the major important things (security fixes) and when it is important 298to upgrade. 299 300 a. Call php bin/createNewsEntry in your local phpweb checkout 301 302 b. Add the content for the news entry 303 3044. Commit all the changes (``include/version.inc``, ``archive/archive.xml``, 305``archive/entries/YYYY-MM-DD-N.xml``) 306 3075. Wait an hour or two, then send a mail to php-announce@lists.php.net, 308php-general@lists.php.net and internals@lists.php.net with a text similar to 309the news entry. 310Please make sure that the mail to php-announce@ is its own completely seperate email. 311This is to make sure that repiles to the announcement on php-general@ or internals@ 312will not accidentally hit the php-announce@ mailinglist. 313
