README.RELEASE_PROCESS 12.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
=======================
  PHP Release Process
=======================

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

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

11 12
2. Package two days before a release. So if the release is to be on Thursday,
package on Tuesday. Think about timezones as well.
13

14 15 16 17 18 19 20 21 22 23 24 25 26
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 bases 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/
27 28 29 30
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.
31

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

34
7. Moving extensions from/to PECL requires write acces to the destination.
35
Most developers should have this. 
36 37

Moving extensions from php-src to PECL
38 39 40 41 42 43 44 45
- 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
46 47 48 49 50 51 52

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

53 54
For Moving extensions from PECL to php-src the svn mv has to be tone the other
way round.
55 56 57 58

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

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

61 62 63
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
64 65
credits files in ext/standard.

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

68
5. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.
69 70
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"``
71

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

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

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

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

82
10. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and ``NEWS``
83 84 85 86 87
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.

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

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

96
13. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a
97
directory "downloads/". Copy them into there, so that the system can generate
98
MD5 sums. If you do not have this directory, talk to Derick or Dan.
99

100
14. Now the RC can be found on http://downloads.php.net/yourname,
101 102
f.e. http://downloads.php.net/derick/

103
15. Once the release has been tagged, contact the PHP Windows development team
104 105 106 107 108 109 110 111 112 113 114 115
(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.

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**
116
``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``.
117 118
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
119
as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan,
120 121 122 123 124 125
Derick) run the following commands for you:

``ssh lists.php.net``

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

126
3. Update ``qa.git/include/release-qa.php`` with the appropriate information.
127 128
   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.
129

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

133
   Note: Remember to update the MD5 checksum information.
134

135
4. 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 140

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

141
5. Commit and push those changes:
142

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

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

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

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

154
2. If a CVE commit needs to be merged to the release, then have it committed to
155 156 157
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.
158

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

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

165 166
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)
167

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

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

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

174 175 176
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).
177

178 179
10. Generate the GPG signature files for the archives.
  ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx``
180

181 182 183
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;
184 185 186 187 188
    git submodule update;
    cd distributions;
    git pull origin master;
    cd ..;
    git commit distributions;
189 190 191
    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
192

193 194
12. Once the release has been tagged, contact the PHP Windows development team
(internals-win@lists.php.net) so that Windows binaries can be created.
195

196 197 198
Getting the stable release announced
------------------------------------

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

202 203
 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the
    highest branch, otherwise you have to do this manually, see point 1.b
204

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

208 209 210 211 212 213 214 215
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

216
 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums
217

218 219 220
 e. set ``$PHP_X_RC`` to false!

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

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

225 226 227
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.
228 229 230 231 232

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
233
f.e. ``ChangeLog-5.php`` from the NEWS file
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248

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

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

  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

255
6. Add a short notice to phpweb stating that there is a new release, and
256 257 258 259 260 261 262
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

263 264 265 266 267
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
268 269 270 271

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.
272 273 274
Please make sure that the mail to php-announce@ is its own completely seperate email.
This is to make sure that repiles to the announcement on php-general@ or internals@
will not accidentally hit the php-announce@ mailinglist.
275

276
Re-releasing the same version (or -pl)
277
--------------------------------------
278 279 280 281 282 283 284 285 286 287 288 289 290

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

291 292 293
 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums

 f. Make sure there are no outdated "notes" or edited "date" keys in the
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309
 ``$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.
310 311 312
Please make sure that the mail to php-announce@ is its own completely seperate email.
This is to make sure that repiles to the announcement on php-general@ or internals@
will not accidentally hit the php-announce@ mailinglist.