php-src/README.RELEASE_PROCESS

=======================
  PHP Release Process
=======================

General notes and tips
----------------------

1. Do not release on Fridays, Saturdays or Sundays
because the sysadmins can not upgrade stuff then.

2. Package the day before a release. So if the release is to be on Thursday,
package on Wednesday.

3. Ensure that Windows builds will work before packaging

4. Follow all steps to the letter. When unclear ask previous RM's (Derick/Ilia)
before proceeding. Ideally make sure that for the first releases one of the
previous RM's is around to answer questions. For the steps related to the
php/QA/bug websites try to have someone from the webmaster team (Bjori) on hand.

5. Verify the tags to be extra sure everything was tagged properly.

6. Moving extensions from/to PECL requires write acces to the destination.
Most developers should have this. 

Moving extensions from php-src to PECL
- Checkout the pecl directory, most likely you want a sparse-root checkout
  svn co --depth=empty https://svn.php.net/repository/pecl
- Create an directory for the extension incl. branch and tag structure,
  no trunk at this point and commit this to svn
  cd pecl; mkdir foo foo/tags foo/branches; svn add foo; svn commit
- Move the extension from php-src to the new location
  svn mv https://svn.php.net/repository/php/php-src/trunk/ext/foo \
         https://svn.php.net/repository/pecl/foo/trunk

If the extension is still usable or not dead, in cooperation with the extension
maintainers if any:
- create the pecl.php.net/foo package and its content, license, maintainer
- create the package.xml, commit
- release the package

For Moving extensions from PECL to php-src the svn mv has to be tone the other
way round.

Rolling a non stable release (alpha/beta/RC)
--------------------------------------------

1. Check windows snapshot builder logs (http://windows.php.net/downloads/snaps/ the last revision)

2. run the "scripts/dev/credits" script in php-src and commit the changes in the
credits files in ext/standard.

3. Checkout the release branch for this release (e.g., PHP-5.4.2).

4. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.
Do not use abbreviations for alpha and beta.

5. Commit these changes to the branch with ``git commit -a``.

6. Tag the repository with the version, e.g.: 
``git tag -u YOURKEYID php-5.4.2RC2``

7. Push the changes to the main repo:
``git push --tags origin HEAD``

8. run: ``./makedist 5.4.2RC2``, this will export the tree, create configure
and build three tarballs (gz,bz2 and xz). Make sure you use the same GNU Bison
version as snaps. Recent bison version are known to break ZTS.

9. Copy those three tarballs to www.php.net, in your homedir there should be a
directory "downloads/". Copy them into there, so that the system can generate
MD5 sums. If you do not have this directory, talk to Derick.

10. Now the RC can be found on http://downloads.php.net/yourname,
f.e. http://downloads.php.net/derick/

11. Once the release has been tagged, contact the PHP Windows development team
(internals-win@lists.php.net) so that Windows binaries can be created. Once
those are made, they should be placed into the same directory as the source snapshots.

12. Notify the documentation team if documentations for new features are
not yet available but a stable release is imminent.

Getting the non stable release (alpha/beta/RC) announced
--------------------------------------------------------

1. Send an email (see example here: http://news.php.net/php.internals/19486)
**To** ``internals@lists.php.net`` and ``php-general@lists.php.net`` lists
pointing out "the location of the release" and "the possible release date of
either the next RC, or the final release".

2. Send an email (see example here http://news.php.net/php.pear.qa/5201) **To**
``php-qa@lists.php.net`` and ``primary-qa-tests@lists.php.net``.
This email is to notify the selected projects about a new release so that they
can make sure their projects keep working. Make sure that you have been setup
as a moderator for ``primary-qa-tests@lists.php.net`` by having someone (Wez,
Derick) run the following commands for you:

``ssh lists.php.net``

``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``

3. Update ``qa.git/include/release-qa.php`` with the appropriate information.
   See the documentation within release-qa.php for more information, but all releases
   and RCs are configured here. Only $QA_RELEASES needs to be edited.

   Example: When rolling an RC, set the 'rc' with appropriate information for the
   given version.

   Note: Remember to update the MD5 checksum information.

4. Update ``php.git/include/version.inc`` (x=major version number)

 a. ``$PHP_x_RC`` = "5.4.0RC1"

 b. ``$PHP_x_RC_DATE`` = "06 September 2007"

5. Commit and push those changes:

 a. ``git commit -a && git push origin master``

6. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the
INSTALL and win32/install.txt files which are generated from the PHP manual sources.

7. Publish the announce on www.php.net as well (for all releases, alpha, RCs or other)

Rolling a stable release
------------------------

1. Check windows snapshot builder logs (http://snaps.php.net/win32/snapshot-STABLE.log f.e.)

2. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.

3. **Merge** all related sections in NEWS (f.e. merge the 5.4.1RC1 and 5.4.0 sections)

4. Commit those changes

5. run the "scripts/dev/credits" script in php-src and commit the changes in the
credits files in ext/standard.

6. tag the repository with the version f.e. "``git tag -s php-5.4.1``"
(of course, you need to change that to the version you're rolling an RC for).
When making 5.X release, you need to tag the Zend directory separately!!

7. Bump up the version numbers in ``main/php_version.h``, ``configure.in`` and
possibly ``NEWS`` again, to the **next** version. F.e. if the release candidate
was "5.4.1RC1" then the new one should be "5.4.1RC2-dev" - regardless if we get
a new RC or not. This is to make sure ``version_compare()`` can correctly work.

8. Commit those changes

9. Log in onto the snaps box and go into the correct tree (f.e. the PHP-5.4
branch if you're rolling 5.5.x releases).

10. You do not have to update the tree, but of course you can with "``git pull
origin <branch>``".

11. run: ``./makedist php 5.4.1``, this will export the tree, create configure
and build two tarballs (one gz and one bz2).

12. Commit those two tarballs to web/php-distributions.git, then update the git
    submodule reference in web/php.git: 
    git submodule init;
    git submodule update;
    cd distributions;
    git pull origin master;
    cd ..;
    git commit distributions;
    git push;

13. Once the release has been tagged, contact the PHP Windows development team
(internals-win@lists.php.net) so that Windows binaries can be created. Once
those are made, they should be committed to SVN too.

14. Check if the pear files are updated (phar for 5.1+ or run pear/make-pear-bundle.php with 4.4)

15. When making a final release, also remind the PHP Windows development team
(internals-win@lists.php.net) to prepare the installer packages for Win32.

16. Make sure proper documentation exists for all new features/changes.
Coordinate the release with the PHP Documentation team.

Getting the stable release announced
------------------------------------

1. Run the bumpRelease script for phpweb on your local checkout

 a. ``php bin/bumpRelease 5`` (or ``php bin/bumpRelease 4`` for PHP4)

 b. In case multiple PHP minor versions are in active development you have
    to manually copy the old information to include/releases.inc

2. Edit ``phpweb/include/version.inc`` and change (X=major release number):

 a. ``$PHP_X_VERSION`` to the correct version

 b. ``$PHP_X_DATE`` to the release date

 c. ``$PHP_X_MD5`` array and update all the md5 sums

 d. set ``$PHP_X_RC`` to false!

 e. Make sure there are no outdated "notes" or edited "date" keys in the
 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array

 f. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")

3. Update the ChangeLog file for the given major version
f.e. ``ChangeLog-5.php`` from the NEWS file

 a. go over the list and put every element on one line

 b. check for &, < and > and escape them if necessary

 c. remove all the names at the ends of lines

 d. for marking up, you can do the following (with VI):

  I. ``s/^- /<li>/``

  II. ``s/$/<\/li>/``

  III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``

  IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``

  V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/``

4. ``cp releases/5_4_0.php releases/5_4_1.php``

5. ``git add releases/5_4_1.php``

6. Update the ``releases/*.php`` file with relevant data. The release
announcement file should list in detail:

 a. security fixes,

 b. changes in behavior (whether due to a bug fix or not)

7. Add a short notice to phpweb stating that there is a new release, and
highlight the major important things (security fixes) and when it is important
to upgrade.

 a. Call php bin/createNewsEntry in your local phpweb checkout

 b. Add the content for the news entry

8. Commit all the changes.

9. Wait an hour or two, then send a mail to php-announce@lists.php.net,
php-general@lists.php.net and internals@lists.php.net with a text similar to
http://news.php.net/php.internals/17222.

Re-releasing the same version (or -pl)
--------------------------------------

1. Commit the new binaries to ``phpweb/distributions/``

2. Edit ``phpweb/include/version.inc`` and change (X=major release number):

 a. If only releasing for one OS, make sure you edit only those variables

 b. ``$PHP_X_VERSION`` to the correct version

 c. ``$PHP_X_DATE`` to the release date

 d. ``$PHP_X_MD5`` array and update all the md5 sums

 e. Make sure there are no outdated "notes" or edited "date" keys in the
 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array

3. Add a short notice to phpweb stating that there is a new release, and
highlight the major important things (security fixes) and when it is important
to upgrade.

 a. Call php bin/createNewsEntry in your local phpweb checkout

 b. Add the content for the news entry

4. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
``archive/entries/YYYY-MM-DD-N.xml``)

5. Wait an hour or two, then send a mail to php-announce@lists.php.net,
php-general@lists.php.net and internals@lists.php.net with a text similar to
the news entry.