xref: /PHP-7.2/README.RELEASE_PROCESS (revision 60a69dae)
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 the tests on Travis CI are green.
15See: https://travis-ci.org/php/php-src/builds
16It is recommended to do so a couple of days before the packaging day, to
17have enough time to investigate failures, communicate with the authors and
18commit the fixes.
19The RM for the branch is also responsible for keeping the CI green on
20ongoing basis between the releases. Check the CI status for your branch
21periodically and resolve the failures ASAP. See more in:
22https://wiki.php.net/rfc/travis_ci
23
244. Ensure that Windows builds will work before packaging
25
265. Follow all steps to the letter. When unclear ask previous RM's (David/Julien/
27Johannes/Stas/Derick/Ilia) before proceeding. Ideally make sure that for the
28first releases one of the previous RM's is around to answer questions. For the
29steps related to the php/QA/bug websites try to have someone from the webmaster
30team (Bjori) on hand.
31
326. Verify the tags to be extra sure everything was tagged properly.
33
347. Moving extensions from/to PECL requires write access to the destination.
35Most developers should have this.
36
37Moving extensions from php-src to PECL
38- Checkout the pecl directory, most likely you want a sparse-root checkout
39  svn co --depth=empty https://svn.php.net/repository/pecl
40- Create an directory for the extension incl. branch and tag structure,
41  no trunk at this point and commit this to svn
42  cd pecl; mkdir foo foo/tags foo/branches; svn add foo; svn commit
43- Move the extension from php-src to the new location
44  svn mv https://svn.php.net/repository/php/php-src/trunk/ext/foo \
45         https://svn.php.net/repository/pecl/foo/trunk
46
47If the extension is still usable or not dead, in cooperation with the extension
48maintainers if any:
49- create the pecl.php.net/foo package and its content, license, maintainer
50- create the package.xml, commit
51- release the package
52
53For Moving extensions from PECL to php-src the svn mv has to be tone the other
54way round.
55
56Rolling a non stable release (alpha/beta/RC)
57--------------------------------------------
58
591. Check windows snapshot builder logs (http://windows.php.net/downloads/snaps/ the last revision)
60
612. Check the tests at https://travis-ci.org/php/php-src/builds
62
633. run the "scripts/dev/credits" script in php-src and commit the changes in the
64credits files in ext/standard.
65
664. Checkout the release branch for this release (e.g., PHP-5.4.2) from the main branch.
67
685. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``.
69Do not use abbreviations for alpha and beta. Do not use dashes, you should
70``#define PHP_VERSION "5.4.22RC1"`` and not ``#define PHP_VERSION "5.4.22-RC1"``
71
726. 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
757. Check ./sapi/cli/php -v output for version matching.
76
778. If all is right, commit the changes to the release branch with ``git commit -a``.
78
799. Tag the repository release branch with the version, e.g.:
80``git tag -u YOURKEYID php-5.4.2RC2``
81
8210. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and ``NEWS``
83in the *main* branch (PHP-5.4 for example) to prepare for the **next** version.
84F.e. if the RC is "5.4.1RC1" then the new one should be "5.4.2-dev" - regardless if we get
85a new RC or not. This is to make sure ``version_compare()`` can correctly work.
86Commit the changes to the main branch.
87
8811. Push the changes to the main repo, the tag, the main branch and the release branch :
89``git push --tags origin HEAD``
90``git push origin {main branch}``
91``git push origin {release branch}``
92
9312. run: ``PHPROOT=. ./makedist 5.4.2RC2``, this will export the tree, create configure
94and build three tarballs (gz, bz2 and xz).
95
9613. run ``scripts/dev/gen_verify_stub <version> [identity]``, this will sign the tarballs
97and output verification information to be included in announcement email
98
9914. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a
100directory "public_html/". Copy them into there, so that the system can generate
101MD5 sums. If you do not have this directory, create it.
102
10315. Now the RC can be found on http://downloads.php.net/~yourname,
104f.e. http://downloads.php.net/~derick/
105
10616. Once the release has been tagged, contact the release-managers@ distribution list
107so that Windows binaries can be created.  Once those are made, they can be found at
108http://windows.php.net/download
109
110Getting the non stable release (alpha/beta/RC) announced
111--------------------------------------------------------
112
1131. Update ``qa.git/include/release-qa.php`` with the appropriate information.
114   See the documentation within release-qa.php for more information, but all releases
115   and RCs are configured here. Only $QA_RELEASES needs to be edited.
116
117   Example: When rolling an RC, set the 'rc' with appropriate information for the
118   given version.
119
120   Note: Remember to update the MD5 and sha256 checksum information.
121
1222. Update ``web/php.git/include/version.inc`` (x=major version number)
123
124 a. ``$PHP_x_RC`` = "5.4.0RC1"  (should be set to "false" before)
125
126 b. ``$PHP_x_RC_DATE`` = "06 September 2007"
127
1283. Add a short notice to phpweb stating that there is a new release, and
129highlight the major important things (security fixes) and when it is important
130to upgrade.
131
132 a. Call php bin/createNewsEntry in your local phpweb checkout
133    Use category "releases" for all stable releases.
134    Use category "frontpage" for X.Y.0 non-stable releases only (news only).
135
136 b. Add the content for the news entry. Be sure to include the text:
137    "THIS IS A DEVELOPMENT PREVIEW - DO NOT USE IT IN PRODUCTION!"
138
1394. Commit and push changes to qa and web
140
141*Wait for web and qa sites to update with new information before sending announce*
142
1435. Send an email **To** ``internals@lists.php.net`` and ``php-general@lists.php.net``
144lists pointing out "the location of the release" and "the possible release date of
145either the next RC, or the final release". Include in this information the verification
146information output by ``gen_verify_stub``.
147
1486. Send an email (see example here http://news.php.net/php.pear.qa/5201) **To**
149``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``.
150This email is to notify the selected projects about a new release so that they
151can make sure their projects keep working. Make sure that you have been setup
152as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan,
153Derick) run the following commands for you:
154
155``ssh lists.php.net``
156
157``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``
158
1597. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the
160INSTALL and win32/install.txt files which are generated from the PHP manual sources.
161
162Rolling a stable release
163------------------------
164
1651. Checkout your release branch, you should have created when releasing previous RC
166and bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``.
167
1682. If a CVE commit needs to be merged to the release, then have it committed to
169the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3,
170merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch.
171Don't forget to update NEWS manually in an extra commit then.
172
1733. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are
174still passing.
175
1764. run the "scripts/dev/credits" script in php-src and commit the changes in the
177credits files in ext/standard.
178
1795. Compile and make test, with and without ZTS, using the right Bison version
180(for example, for 5.5, Bison 2.4.1 is used)
181
1826. Check ./sapi/cli/php -v output for version matching.
183
1847. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``"
185
1868. Push the tag f.e. "``git push origin php-5.4.1``"
187
1889. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure
189and build three tarballs (gz, bz2 and xz).
190Check if the pear files are updated (phar).
191
19210. Generate the GPG signature files for the archives.
193  ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx``
194
19511. Commit and push all the tarballs and signature files to web/php-distributions.git,
196    then update the git submodule reference in web/php.git:
197    ``git submodule init;
198    git submodule update;
199    cd distributions;
200    git pull origin master;
201    cd ..;
202    git commit distributions;
203    git push;``
204This is to fetch the last commit id from php-distributions.git and commit this
205last commit id to web/php.git, then, mirrors will now sync
206
20712. Once the release has been tagged, contact release managers, windows builders, and package maintainers
208so that they can build releases. Do not send this announcement to any public lists.
209
210Getting the stable release announced
211------------------------------------
212
2131. Update phpweb/include/releases.inc with the old release info
214  (updates the download archives)
215
216 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the
217    highest branch, otherwise you have to do this manually, see point 1.b
218
219 b. In case multiple PHP minor versions are in active development you have
220    to manually copy the old information to include/releases.inc
221
2222. Edit ``phpweb/include/version.inc`` and change (X=major release number):
223
224 a. ``$PHP_X_VERSION`` to the correct version
225
226 b. ``$PHP_X_DATE`` to the release date
227
228 c. ``$PHP_X_MD5`` array and update all the md5 sums
229
230 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums
231
232 e. set ``$PHP_X_RC`` to false!
233
234 f. Make sure there are no outdated "notes" or edited "date" keys in the
235 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
236
237 g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")
238
2393. Create the release file (releases/x_y_z.php)
240   Usually we use the same content as for point 6, but included in php template
241   instead of the release xml.
242
2434. Update php-qa/include/release-qa.php and add the next version as an QARELEASE
244   (prepare for next RC)
245
2465. Update the ChangeLog file for the given major version
247f.e. ``ChangeLog-5.php`` from the NEWS file
248
249 a. go over the list and put every element on one line
250
251 b. check for &, < and > and escape them if necessary
252
253 c. remove all the names at the ends of lines
254
255 d. for marking up, you can do the following (with VI):
256
257  I. ``s/^- /<li>/``
258
259  II. ``s/$/<\/li>/``
260
261  III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``
262
263  IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``
264
265  V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/``
266
267  e. You may want to try php-web/bin/news2html to automate this task
268
2696. Add a short notice to phpweb stating that there is a new release, and
270highlight the major important things (security fixes) and when it is important
271to upgrade.
272
273 a. Call php bin/createNewsEntry in your local phpweb checkout
274
275 b. Add the content for the news entry
276
2777. **Check mirrors have been synced before announcing or pushing news**
278  Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror
279  Try several mirrors, mirrors may update slowly (may take an hour)
280
2818. Commit all the changes to their respective git repos
282
2839. Please note down the sha256 and the PGP signature (.asc). These *must* be
284   included in the release mail.
28510. Wait an hour or two, then send a mail to php-announce@lists.php.net,
286php-general@lists.php.net and internals@lists.php.net with a text similar to
287http://news.php.net/php.internals/17222.
288Please make sure that the mail to php-announce@ is its own completely separate email.
289This is to make sure that replies to the announcement on php-general@ or internals@
290will not accidentally hit the php-announce@ mailinglist.
291
292Re-releasing the same version (or -pl)
293--------------------------------------
294
2951. Commit the new binaries to ``phpweb/distributions/``
296
2972. Edit ``phpweb/include/version.inc`` and change (X=major release number):
298
299 a. If only releasing for one OS, make sure you edit only those variables
300
301 b. ``$PHP_X_VERSION`` to the correct version
302
303 c. ``$PHP_X_DATE`` to the release date
304
305 d. ``$PHP_X_MD5`` array and update all the md5 sums
306
307 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums
308
309 f. Make sure there are no outdated "notes" or edited "date" keys in the
310 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
311
3123. Add a short notice to phpweb stating that there is a new release, and
313highlight the major important things (security fixes) and when it is important
314to upgrade.
315
316 a. Call php bin/createNewsEntry in your local phpweb checkout
317
318 b. Add the content for the news entry
319
3204. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
321``archive/entries/YYYY-MM-DD-N.xml``)
322
3235. Wait an hour or two, then send a mail to php-announce@lists.php.net,
324php-general@lists.php.net and internals@lists.php.net with a text similar to
325the news entry.
326Please make sure that the mail to php-announce@ is its own completely separate email.
327This is to make sure that replies to the announcement on php-general@ or internals@
328will not accidentally hit the php-announce@ mailinglist.
329
330New Release Manager Checklist
331-----------------------------
332
3331. Email systems@ to get setup for access to downloads.php.net and to be added to the
334   release-managers@ distribution list.
335
3362. Create a GPG key for your @php.net address and publish it by editing `include/gpg-keys.inc`
337   in the `web-php` repository, adding the output of `gpg --fingerprint "$USER@php.net"`. Let
338   one or more of the previous RMs sign your key. Publish your public key to pgp.mit.edu with:
339   `gpg --keyserver pgp.mit.edu --send-keys $KEYID`
340
3413. Request karma to eding main/php_version.h. Possibly karma for other restricted parts of
342   php-src might come in question.
343
3444. Request karma for web/qa.git and web/php.git for publishing release announcements.
345
3465. Request moderation access to announce@php.net and primary-qa-tester@lists.php.net lists, to
347   be able to moderate your release announcements. All the announcements should be sent from
348   the @php.net alias.
349