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 Windows builds will work before packaging 15 164. Follow all steps to the letter. When unclear ask previous RM's (David/Julien/ 17Johannes/Stas/Derick/Ilia) before proceeding. Ideally make sure that for the 18first releases one of the previous RM's is around to answer questions. For the 19steps related to the php/QA/bug websites try to have someone from the webmaster 20team (Bjori) on hand. 21 225. Verify the tags to be extra sure everything was tagged properly. 23 246. Moving extensions from/to PECL requires write acces to the destination. 25Most developers should have this. 26 27Moving extensions from php-src to PECL 28- Checkout the pecl directory, most likely you want a sparse-root checkout 29 svn co --depth=empty https://svn.php.net/repository/pecl 30- Create an directory for the extension incl. branch and tag structure, 31 no trunk at this point and commit this to svn 32 cd pecl; mkdir foo foo/tags foo/branches; svn add foo; svn commit 33- Move the extension from php-src to the new location 34 svn mv https://svn.php.net/repository/php/php-src/trunk/ext/foo \ 35 https://svn.php.net/repository/pecl/foo/trunk 36 37If the extension is still usable or not dead, in cooperation with the extension 38maintainers if any: 39- create the pecl.php.net/foo package and its content, license, maintainer 40- create the package.xml, commit 41- release the package 42 43For Moving extensions from PECL to php-src the svn mv has to be tone the other 44way round. 45 46Rolling a non stable release (alpha/beta/RC) 47-------------------------------------------- 48 491. Check windows snapshot builder logs (http://windows.php.net/downloads/snaps/ the last revision) 50 512. run the "scripts/dev/credits" script in php-src and commit the changes in the 52credits files in ext/standard. 53 543. Checkout the release branch for this release (e.g., PHP-5.4.2) from the main branch. 55 564. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``. 57Do not use abbreviations for alpha and beta. Do not use dashes, you should 58``#define PHP_VERSION "5.4.22RC1"`` and not ``#define PHP_VERSION "5.4.22-RC1"`` 59 605. Compile and make test, with and without ZTS, using the right Bison version 61(for example, for 5.5, Bison 2.4.1 is used) 62 636. Check ./sapi/cli/php -v output for version matching. 64 657. If all is right, commit the changes to the release branch with ``git commit -a``. 66 678. Tag the repository release branch with the version, e.g.: 68``git tag -u YOURKEYID php-5.4.2RC2`` 69 709. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and ``NEWS`` 71in the *main* branch (PHP-5.4 for example) to prepare for the **next** version. 72F.e. if the RC is "5.4.1RC1" then the new one should be "5.4.2-dev" - regardless if we get 73a new RC or not. This is to make sure ``version_compare()`` can correctly work. 74Commit the changes to the main branch. 75 7610. Push the changes to the main repo, the tag, the main branch and the release branch : 77``git push --tags origin HEAD`` 78``git push origin {main branch}`` 79``git push origin {release branch}`` 80 8111. run: ``PHPROOT=. ./makedist 5.4.2RC2``, this will export the tree, create configure 82and build three tarballs (gz, bz2 and xz). 83 8412. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a 85directory "downloads/". Copy them into there, so that the system can generate 86MD5 sums. If you do not have this directory, talk to Derick or Dan. 87 8813. Now the RC can be found on http://downloads.php.net/yourname, 89f.e. http://downloads.php.net/derick/ 90 9114. Once the release has been tagged, contact the PHP Windows development team 92(internals-win@lists.php.net) so that Windows binaries can be created. Once 93those are made, they should be placed into the same directory as the source snapshots. 94 95Getting the non stable release (alpha/beta/RC) announced 96-------------------------------------------------------- 97 981. Send an email (see example here: http://news.php.net/php.internals/19486) 99**To** ``internals@lists.php.net`` and ``php-general@lists.php.net`` lists 100pointing out "the location of the release" and "the possible release date of 101either the next RC, or the final release". 102 1032. Send an email (see example here http://news.php.net/php.pear.qa/5201) **To** 104``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``. 105This email is to notify the selected projects about a new release so that they 106can make sure their projects keep working. Make sure that you have been setup 107as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan, 108Derick) run the following commands for you: 109 110``ssh lists.php.net`` 111 112``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address`` 113 1143. Update ``qa.git/include/release-qa.php`` with the appropriate information. 115 See the documentation within release-qa.php for more information, but all releases 116 and RCs are configured here. Only $QA_RELEASES needs to be edited. 117 118 Example: When rolling an RC, set the 'rc' with appropriate information for the 119 given version. 120 121 Note: Remember to update the MD5 checksum information. 122 1234. Update ``web/php.git/include/version.inc`` (x=major version number) 124 125 a. ``$PHP_x_RC`` = "5.4.0RC1" (should be set to "false" before) 126 127 b. ``$PHP_x_RC_DATE`` = "06 September 2007" 128 1295. Commit and push those changes: 130 131 a. ``git commit -a && git push origin master`` 132 1336. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the 134INSTALL and win32/install.txt files which are generated from the PHP manual sources. 135 136Rolling a stable release 137------------------------ 138 1391. Checkout your release branch, you should have created when releasing previous RC 140and bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``. 141 1422. If a CVE commit needs to be merged to the release, then have it commited to 143the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3, 144merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch. 145Don't forget to update NEWS manually in an extra commit then. 146 1473. Commit those changes 148 1494. run the "scripts/dev/credits" script in php-src and commit the changes in the 150credits files in ext/standard. 151 1525. Compile and make test, with and without ZTS, using the right Bison version 153(for example, for 5.5, Bison 2.4.1 is used) 154 1556. Check ./sapi/cli/php -v output for version matching. 156 1577. tag the repository with the version f.e. "``git tag -s php-5.4.1``" 158 1598. Push the tag f.e. "``git push origin php-5.4.1``" 160 1619. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure 162and build three tarballs (gz, bz2 and xz). 163Check if the pear files are updated (phar). 164 16510. Generate the GPG signature files for the archives. 166 ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx`` 167 16811. Commit and push all the tarballs and signature files to web/php-distributions.git, 169 then update the git submodule reference in web/php.git: 170 ``git submodule init; 171 git submodule update; 172 cd distributions; 173 git pull origin master; 174 cd ..; 175 git commit distributions; 176 git push;`` 177This is to fetch the last commit id from php-distributions.git and commit this 178last commit id to web/php.git, then, mirrors will now sync 179 18012. Once the release has been tagged, contact the PHP Windows development team 181(internals-win@lists.php.net) so that Windows binaries can be created. 182 183Getting the stable release announced 184------------------------------------ 185 1861. Run the bumpRelease script for phpweb on your local checkout 187 188 a. ``php bin/bumpRelease 5`` to create the release file (releases/x_y_z.php) 189 The release announcement file should list in detail security fixes and 190 changes in behavior (whether due to a bug fix or not). 191 192 b. In case multiple PHP minor versions are in active development you have 193 to manually copy the old information to include/releases.inc 194 1952. Edit ``phpweb/include/version.inc`` and change (X=major release number): 196 197 a. ``$PHP_X_VERSION`` to the correct version 198 199 b. ``$PHP_X_DATE`` to the release date 200 201 c. ``$PHP_X_MD5`` array and update all the md5 sums 202 203 d. set ``$PHP_X_RC`` to false! 204 205 e. Make sure there are no outdated "notes" or edited "date" keys in the 206 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array 207 208 f. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows") 209 2103. Update phpweb/include/releases.php with the old release info 211 (updates the download archives) 212 2134. Update php-qa/include/release-qa.php and add the next version as an QARELEASE 214 (prepare for next RC) 215 2165. Update the ChangeLog file for the given major version 217f.e. ``ChangeLog-5.php`` from the NEWS file 218 219 a. go over the list and put every element on one line 220 221 b. check for &, < and > and escape them if necessary 222 223 c. remove all the names at the ends of lines 224 225 d. for marking up, you can do the following (with VI): 226 227 I. ``s/^- /<li>/`` 228 229 II. ``s/$/<\/li>/`` 230 231 III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/`` 232 233 IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/`` 234 235 V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/`` 236 237 e. You may want to try php-web/bin/news2html to automate this task 238 2396. Add a short notice to phpweb stating that there is a new release, and 240highlight the major important things (security fixes) and when it is important 241to upgrade. 242 243 a. Call php bin/createNewsEntry in your local phpweb checkout 244 245 b. Add the content for the news entry 246 2477. **Check mirrors have been synced before announcing or pushing news** 248 Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror 249 Try several mirrors, mirrors may update slowly (may take an hour) 250 2518. Commit all the changes to their respective git repos 252 2539. Wait an hour or two, then send a mail to php-announce@lists.php.net, 254php-general@lists.php.net and internals@lists.php.net with a text similar to 255http://news.php.net/php.internals/17222. 256 257Re-releasing the same version (or -pl) 258-------------------------------------- 259 2601. Commit the new binaries to ``phpweb/distributions/`` 261 2622. Edit ``phpweb/include/version.inc`` and change (X=major release number): 263 264 a. If only releasing for one OS, make sure you edit only those variables 265 266 b. ``$PHP_X_VERSION`` to the correct version 267 268 c. ``$PHP_X_DATE`` to the release date 269 270 d. ``$PHP_X_MD5`` array and update all the md5 sums 271 272 e. Make sure there are no outdated "notes" or edited "date" keys in the 273 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array 274 2753. Add a short notice to phpweb stating that there is a new release, and 276highlight the major important things (security fixes) and when it is important 277to upgrade. 278 279 a. Call php bin/createNewsEntry in your local phpweb checkout 280 281 b. Add the content for the news entry 282 2834. Commit all the changes (``include/version.inc``, ``archive/archive.xml``, 284``archive/entries/YYYY-MM-DD-N.xml``) 285 2865. Wait an hour or two, then send a mail to php-announce@lists.php.net, 287php-general@lists.php.net and internals@lists.php.net with a text similar to 288the news entry. 289
