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 two days before a release. So if the release is to be on Thursday,
package on Tuesday. Think about timezones as well.

3. Ensure that the tests on Travis CI are green.
See: https://travis-ci.org/php/php-src/builds
It is recommended to do so a couple of days before the packaging day, to
have enough time to investigate failures, communicate with the authors and
commit the fixes.
The RM for the branch is also responsible for keeping the CI green on
ongoing basis between the releases. Check the CI status for your branch
periodically and resolve the failures ASAP. See more in:
https://wiki.php.net/rfc/travis_ci

4. Ensure that Windows builds will work before packaging

5. Follow all steps to the letter. When unclear ask previous RM's (David/Julien/
Johannes/Stas/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.

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

7. Moving extensions from/to PECL requires write access 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 a 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 done 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. Check the tests at https://travis-ci.org/php/php-src/builds

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

4. Checkout the release branch for this release (e.g., PHP-5.4.2) from the main branch.

5. Bump the version numbers in ``main/php_version.h``, ``Zend/zend.h``, ``configure.ac`` and possibly ``NEWS``.
Do not use abbreviations for alpha and beta. Do not use dashes, you should
``#define PHP_VERSION "5.4.22RC1"`` and not ``#define PHP_VERSION "5.4.22-RC1"``

6. Compile and make test, with and without ZTS, using the right Bison version
(for example, for 5.5, Bison 2.4.1 is used)

7. Check ./sapi/cli/php -v output for version matching.

8. If all is right, commit the changes to the release branch with ``git commit -a``.

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

10. Bump the version numbers in ``main/php_version.h``, ``Zend/zend.h``, ``configure.ac`` and ``NEWS``
in the *main* branch (PHP-5.4 for example) to prepare for the **next** version.
F.e. if the RC is "5.4.1RC1" then the new one should be "5.4.2-dev" - regardless if we get
a new RC or not. This is to make sure ``version_compare()`` can correctly work.
Commit the changes to the main branch.

11. Push the changes to the main repo, the tag, the main branch and the release branch :
``git push --tags origin HEAD``
``git push origin {main branch}``
``git push origin {release branch}``

12. run: ``PHPROOT=. ./makedist 5.4.2RC2``, this will export the tree, create configure
and build three tarballs (gz, bz2 and xz).

13. run ``scripts/dev/gen_verify_stub <version> [identity]``, this will sign the tarballs
and output verification information to be included in announcement email

14. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a
directory "public_html/". Copy them into there. If you do not have this directory, create it.

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

16. Once the release has been tagged, contact the release-managers@ distribution list
so that Windows binaries can be created.  Once those are made, they can be found at
http://windows.php.net/download

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

1. 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 sha256 checksum information.

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

 a. ``$PHP_x_RC`` = "5.4.0RC1"  (should be set to "false" before)

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

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
    Use category "frontpage" *and* "releases" for all stable releases.
    Use category "frontpage" for X.Y.0 non-stable releases only (news only).

 b. Add the content for the news entry. Be sure to include the text:
    "THIS IS A DEVELOPMENT PREVIEW - DO NOT USE IT IN PRODUCTION!"

4. Commit and push changes to qa and web

*Wait for web and qa sites to update with new information before sending announce*

5. Send **separate** emails **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". Include in this information the verification
information output by ``gen_verify_stub``.

6. Send **separate** emails (see example here http://news.php.net/php.pear.qa/5201) **To**
``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``.
These emails are 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-tester@lists.php.net`` by having someone (Hannes, Dan,
Derick) run the following commands for you:

``ssh lists.php.net``

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

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

1. Checkout your release branch, you should have created when releasing previous RC
and bump the version numbers in ``main/php_version.h``, ``Zend/zend.h``, ``configure.ac`` and possibly ``NEWS``.

2. If a CVE commit needs to be merged to the release, then have it committed to
the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3,
merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch.
Don't forget to update NEWS manually in an extra commit then.

3. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are
still passing.

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

5. Compile and make test, with and without ZTS, using the right Bison version
(for example, for 5.5, Bison 2.4.1 is used)

6. Check ./sapi/cli/php -v output for version matching.

7. tag the repository with the version f.e. "``git tag -u YOURKEYID php-5.4.1``"

8. Push the tag f.e. "``git push origin php-5.4.1``"

9. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure
and build three tarballs (gz, bz2 and xz).
   Check if the pear files are updated (phar).
   On some systems the behavior of GNU tar can default to produce POSIX compliant archives
with PAX headers. As not every application is compatible with that format, creation of
archives with PAX headers should be avoided. When packaging on such a system, the GNU tar
can be influenced by defining the environment variable TAR_OPTIONS='--format=gnu'.

10. run ``scripts/dev/gen_verify_stub <version> [identity]``, this will sign the tarballs
    and output verification information to be included in announcement email

11. Commit and push all the tarballs and signature files to web/php-distributions.git,
    then update the git submodule reference in web/php.git:
    ``git submodule init;
    git submodule update;
    cd distributions;
    git fetch;
    git pull --rebase origin master;
    cd ..;
    git commit distributions;
    git push;``
This is to fetch the last commit id from php-distributions.git and commit this
last commit id to web/php.git, then, mirrors will now sync

12. Once the release has been tagged, contact release managers, windows builders, and package maintainers
so that they can build releases. Do not send this announcement to any public lists.

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

1. Update phpweb/include/releases.inc with the old release info
  (updates the download archives)

 a. You can run ``php bin/bumpRelease 7 2`` where the first number is
    the major version, and the second number is the minor version
    (7.2 in this example).

 b. If that fails for any non-trivially fixable reason, you can
    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_SHA256`` array and update all the SHA256 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

3. Create the release file (releases/x_y_z.php)
   Usually we use the same content as for point 6, but included in php template
   instead of the release xml.

4. Update php-qa/include/release-qa.php and add the next version as an QARELEASE
   (prepare for next RC)

5. 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); ?>/``

  e. You may want to try php-web/bin/news2html to automate this task

6. 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

7. **Check mirrors have been synced before announcing or pushing news**
  Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror
  Try several mirrors, mirrors may update slowly (may take an hour)

8. Commit all the changes to their respective git repos

9. Please note down the sha256 and the PGP signature (.asc). These *must* be
   included in the release mail.
10. 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.
Please make sure that the mail to php-announce@ is its own completely separate email.
This is to make sure that replies to the announcement on php-general@ or internals@
will not accidentally hit the php-announce@ mailinglist.

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_SHA256`` array and update all the SHA256 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.
Please make sure that the mail to php-announce@ is its own completely separate email.
This is to make sure that replies to the announcement on php-general@ or internals@
will not accidentally hit the php-announce@ mailinglist.

Forking a new release branch
----------------------------

1. One week prior to cutting X.Y.0beta1, warn internals@ that your version's branch
   is about to be cut, and that PHP-X.Y will be moving into feature freeze.
   Try to be specific about when the branch will be cut.
      Example: http://news.php.net/php.internals/99864

2. Just prior to cutting X.Y.0beta1, create the new branch locally.
   Add a commit on master after the branch point clearing the NEWS, UPGRADING
   and UPGRADING.INTERNALS files, updating the version in configure.ac (run
   ./configure to automatically update main/php_versions.h, too) and Zend/zend.h.
   Also list the new branch in README.GIT-RULES.
     Example: http://git.php.net/?p=php-src.git;a=commit;h=a63c99b
   Push the new branch and the commit just added to master.

3. Immediately notify internals@ of the branch cut and advise the new merging order:
     Example: http://news.php.net/php.internals/99903

4. Update php-web:git.php and wiki.php.net/vcs/gitworkflow to reflect the new branch:
     Example: https://github.com/php/web-php/commit/74bcad4c770d95f21b7fbeeedbd76d943bb83f23

5. Notify nlopess@ to add PHP_X_Y tag to gcov.php.net

Preparing for the initial stable version (PHP X.Y.0)
----------------------------------------------------

1. About the time you release the first RC, remind the documentation team
   (phpdoc@lists.php.net) to write the migration guide.  See to it that they
   have done it before you release the initial stable version, since you want
   to link to it in the release announcements.

2. Timely get used to the differences in preparing and announcing a stable
   release.

Prime the selection of the Release Managers of the next version
---------------------------------------------------------------

1. About three months before the scheduled release of the first alpha of the
   next minor or major release, issue a call for volunteers on 
   internals@lists.php.net (cf. http://news.php.net/php.internals/98652).

2. Make sure that there are two or more volunteers, and hold a vote if necessary
   (see https://wiki.php.net/rfc/releaseprocess#release_managers_selection).

3. Help the new release managers with their first steps.

New Release Manager Checklist
-----------------------------

1. Email systems@ to get setup for access to downloads.php.net and to be added to the
   release-managers@ distribution list.

2. Create a GPG key for your @php.net address and publish it by editing `include/gpg-keys.inc`
   in the `web-php` repository, adding the output of `gpg --fingerprint "$USER@php.net"`. Let
   one or more of the previous RMs sign your key. Publish your public key to pgp.mit.edu with:
   `gpg --keyserver pgp.mit.edu --send-keys $KEYID`

3. Request karma to edit main/php_version.h and Zend/zend.h. Possibly karma for other restricted parts of
   php-src might come in question. To edit main/php_version.h in a release branch,
   you need release manager karma in global_avail.

4. Request karma for web/qa.git and web/php.git for publishing release announcements.

5. Request moderation access to announce@php.net and primary-qa-tester@lists.php.net lists, to
   be able to moderate your release announcements. All the announcements should be sent from
   the @php.net alias.