release/src/router/php/README.RELEASE_PROCESS

   1 =======================
   2   PHP Release Process
   3 =======================
   4
   5 General notes and tips
   6 ----------------------
   7
   8 1. Do not release on Fridays, Saturdays or Sundays
   9 because the sysadmins can not upgrade stuff then.
  10
  11 2. Package the day before a release. So if the release is to be on Thursday,
  12 package on Wednesday.
  13
  14 3. Ensure that Windows builds will work before packaging
  15
  16 4. Follow all steps to the letter. When unclear ask previous RM's (Derick/Ilia)
  17 before proceeding. Ideally make sure that for the first releases one of the
  18 previous RM's is around to answer questions. For the steps related to the
  19 php/QA/bug websites try to have someone from the webmaster team (Bjori) on hand.
  20
  21 5. Verify the tags to be extra sure everything was tagged properly.
  22
  23 6. Moving extensions from/to PECL requires write acces to the destination.
  24 Most developers should have this.
  25
  26 Moving extensions from php-src to PECL
  27 - Checkout the pecl directory, most likely you want a sparse-root checkout
  28   svn co --depth=empty https://svn.php.net/repository/pecl
  29 - Create an directory for the extension incl. branch and tag structure,
  30   no trunk at this point and commit this to svn
  31   cd pecl; mkdir foo foo/tags foo/branches; svn add foo; svn commit
  32 - Move the extension from php-src to the new location
  33   svn mv https://svn.php.net/repository/php/php-src/trunk/ext/foo \
  34          https://svn.php.net/repository/pecl/foo/trunk
  35
  36 If the extension is still usable or not dead, in cooperation with the extension
  37 maintainers if any:
  38 - create the pecl.php.net/foo package and its content, license, maintainer
  39 - create the package.xml, commit
  40 - release the package
  41
  42 For Moving extensions from PECL to php-src the svn mv has to be tone the other
  43 way round.
  44
  45 Rolling a non stable release (alpha/beta/RC)
  46 --------------------------------------------
  47
  48 1. Check windows snapshot builder logs (http://windows.php.net/downloads/snaps/ the last revision)
  49
  50 2. run the "scripts/dev/credits" script in php-src and commit the changes in the
  51 credits files in ext/standard.
  52
  53 3. Checkout the release branch for this release (e.g., PHP-5.4.2).
  54
  55 4. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.
  56 Do not use abbreviations for alpha and beta.
  57
  58 5. Commit these changes to the branch with ``git commit -a``.
  59
  60 6. Tag the repository with the version, e.g.:
  61 ``git tag -u YOURKEYID php-5.4.2RC2``
  62
  63 7. Push the changes to the main repo:
  64 ``git push --tags origin HEAD``
  65
  66 8. run: ``./makedist 5.4.2RC2``, this will export the tree, create configure
  67 and build two tarballs (one gz and one bz2).
  68
  69 9. Copy those two tarballs to www.php.net, in your homedir there should be a
  70 directory "downloads/". Copy them into there, so that the system can generate
  71 MD5 sums. If you do not have this directory, talk to Derick.
  72
  73 10. Now the RC can be found on http://downloads.php.net/yourname,
  74 f.e. http://downloads.php.net/derick/
  75
  76 11. Once the release has been tagged, contact the PHP Windows development team
  77 (internals-win@lists.php.net) so that Windows binaries can be created. Once
  78 those are made, they should be placed into the same directory as the source snapshots.
  79
  80 Getting the non stable release (alpha/beta/RC) announced
  81 --------------------------------------------------------
  82
  83 1. Send an email (see example here: http://news.php.net/php.internals/19486)
  84 **To** ``internals@lists.php.net`` and ``php-general@lists.php.net`` lists
  85 pointing out "the location of the release" and "the possible release date of
  86 either the next RC, or the final release".
  87
  88 2. Send an email (see example here http://news.php.net/php.pear.qa/5201) **To**
  89 ``php-qa@lists.php.net`` and ``primary-qa-tests@lists.php.net``.
  90 This email is to notify the selected projects about a new release so that they
  91 can make sure their projects keep working. Make sure that you have been setup
  92 as a moderator for ``primary-qa-tests@lists.php.net`` by having someone (Wez,
  93 Derick) run the following commands for you:
  94
  95 ``ssh lists.php.net``
  96
  97 ``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``
  98
  99 3. Update ``qa.git/include/release-qa.php`` with the appropriate information.
 100    See the documentation within release-qa.php for more information, but all releases
 101    and RCs are configured here. Only $QA_RELEASES needs to be edited.
 102
 103    Example: When rolling an RC, set the 'rc' with appropriate information for the
 104    given version.
 105
 106    Note: Remember to update the MD5 checksum information.
 107
 108 4. Update ``php.git/include/version.inc`` (x=major version number)
 109
 110  a. ``$PHP_x_RC`` = "5.4.0RC1"
 111
 112  b. ``$PHP_x_RC_DATE`` = "06 September 2007"
 113
 114 5. Commit and push those changes:
 115
 116  a. ``git commit -a && git push origin master``
 117
 118 6. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the
 119 INSTALL and win32/install.txt files which are generated from the PHP manual sources.
 120
 121 7. Publish the announce on www.php.net as well (for all releases, alpha, RCs or other)
 122
 123 Rolling a stable release
 124 ------------------------
 125
 126 1. Check windows snapshot builder logs (http://snaps.php.net/win32/snapshot-STABLE.log f.e.)
 127
 128 2. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.
 129
 130 3. **Merge** all related sections in NEWS (f.e. merge the 5.4.1RC1 and 5.4.0 sections)
 131
 132 4. Commit those changes
 133
 134 5. run the "scripts/dev/credits" script in php-src and commit the changes in the
 135 credits files in ext/standard.
 136
 137 6. tag the repository with the version f.e. "``git tag -s php-5.4.1``"
 138 (of course, you need to change that to the version you're rolling an RC for).
 139 When making 5.X release, you need to tag the Zend directory separately!!
 140
 141 7. Bump up the version numbers in ``main/php_version.h``, ``configure.in`` and
 142 possibly ``NEWS`` again, to the **next** version. F.e. if the release candidate
 143 was "5.4.1RC1" then the new one should be "5.4.1RC2-dev" - regardless if we get
 144 a new RC or not. This is to make sure ``version_compare()`` can correctly work.
 145
 146 8. Commit those changes
 147
 148 9. Log in onto the snaps box and go into the correct tree (f.e. the PHP-5.4
 149 branch if you're rolling 5.5.x releases).
 150
 151 10. You do not have to update the tree, but of course you can with "``git pull
 152 origin <branch>``".
 153
 154 11. run: ``./makedist php 5.4.1``, this will export the tree, create configure
 155 and build two tarballs (one gz and one bz2).
 156
 157 12. Commit those two tarballs to web/php-distributions.git, then update the git
 158     submodule reference in web/php.git:
 159     git submodule init;
 160     git submodule update;
 161     cd distributions;
 162     git pull origin master;
 163     cd ..;
 164     git commit distributions;
 165     git push;
 166
 167 13. Once the release has been tagged, contact the PHP Windows development team
 168 (internals-win@lists.php.net) so that Windows binaries can be created. Once
 169 those are made, they should be committed to SVN too.
 170
 171 14. Check if the pear files are updated (phar for 5.1+ or run pear/make-pear-bundle.php with 4.4)
 172
 173 15. When making a final release, also remind the PHP Windows development team
 174 (internals-win@lists.php.net) to prepare the installer packages for Win32.
 175
 176 Getting the stable release announced
 177 ------------------------------------
 178
 179 1. Run the bumpRelease script for phpweb on your local checkout
 180
 181  a. ``php bin/bumpRelease 5`` (or ``php bin/bumpRelease 4`` for PHP4)
 182
 183  b. In case multiple PHP minor versions are in active development you have
 184     to manually copy the old information to include/releases.inc
 185
 186 2. Edit ``phpweb/include/version.inc`` and change (X=major release number):
 187
 188  a. ``$PHP_X_VERSION`` to the correct version
 189
 190  b. ``$PHP_X_DATE`` to the release date
 191
 192  c. ``$PHP_X_MD5`` array and update all the md5 sums
 193
 194  d. set ``$PHP_X_RC`` to false!
 195
 196  e. Make sure there are no outdated "notes" or edited "date" keys in the
 197  ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
 198
 199  f. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")
 200
 201 3. Update the ChangeLog file for the given major version
 202 f.e. ``ChangeLog-5.php`` from the NEWS file
 203
 204  a. go over the list and put every element on one line
 205
 206  b. check for &, < and > and escape them if necessary
 207
 208  c. remove all the names at the ends of lines
 209
 210  d. for marking up, you can do the following (with VI):
 211
 212   I. ``s/^- /<li>/``
 213
 214   II. ``s/$/<\/li>/``
 215
 216   III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``
 217
 218   IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``
 219
 220   V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/``
 221
 222 4. ``cp releases/5_4_0.php releases/5_4_1.php``
 223
 224 5. ``git add releases/5_4_1.php``
 225
 226 6. Update the ``releases/*.php`` file with relevant data. The release
 227 announcement file should list in detail:
 228
 229  a. security fixes,
 230
 231  b. changes in behavior (whether due to a bug fix or not)
 232
 233 7. Add a short notice to phpweb stating that there is a new release, and
 234 highlight the major important things (security fixes) and when it is important
 235 to upgrade.
 236
 237  a. Call php bin/createNewsEntry in your local phpweb checkout
 238
 239  b. Add the content for the news entry
 240
 241 8. Commit all the changes.
 242
 243 9. Wait an hour or two, then send a mail to php-announce@lists.php.net,
 244 php-general@lists.php.net and internals@lists.php.net with a text similar to
 245 http://news.php.net/php.internals/17222.
 246
 247 Re-releasing the same version (or -pl)
 248 --------------------------------------
 249
 250 1. Commit the new binaries to ``phpweb/distributions/``
 251
 252 2. Edit ``phpweb/include/version.inc`` and change (X=major release number):
 253
 254  a. If only releasing for one OS, make sure you edit only those variables
 255
 256  b. ``$PHP_X_VERSION`` to the correct version
 257
 258  c. ``$PHP_X_DATE`` to the release date
 259
 260  d. ``$PHP_X_MD5`` array and update all the md5 sums
 261
 262  e. Make sure there are no outdated "notes" or edited "date" keys in the
 263  ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
 264
 265 3. Add a short notice to phpweb stating that there is a new release, and
 266 highlight the major important things (security fixes) and when it is important
 267 to upgrade.
 268
 269  a. Call php bin/createNewsEntry in your local phpweb checkout
 270
 271  b. Add the content for the news entry
 272
 273 4. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
 274 ``archive/entries/YYYY-MM-DD-N.xml``)
 275
 276 5. Wait an hour or two, then send a mail to php-announce@lists.php.net,
 277 php-general@lists.php.net and internals@lists.php.net with a text similar to
 278 the news entry.