xref: /PHP-7.1/README.RELEASE_PROCESS (revision 7f6387b5)
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.in`` 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.in`` 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 "downloads/". Copy them into there, so that the system can generate
101MD5 sums. If you do not have this directory, talk to Derick or Dan.
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 PHP Windows development team
107(internals-win@lists.php.net) so that Windows binaries can be created. Once
108those are made, they should be placed into the same directory as the source snapshots.
109
110Getting the non stable release (alpha/beta/RC) announced
111--------------------------------------------------------
112
1131. Send an email **To** ``internals@lists.php.net`` and ``php-general@lists.php.net``
114lists pointing out "the location of the release" and "the possible release date of
115either the next RC, or the final release". Include in this information the verification
116information output by ``gen_verify_stub``.
117
1182. Send an email (see example here http://news.php.net/php.pear.qa/5201) **To**
119``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``.
120This email is to notify the selected projects about a new release so that they
121can make sure their projects keep working. Make sure that you have been setup
122as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan,
123Derick) run the following commands for you:
124
125``ssh lists.php.net``
126
127``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``
128
1293. Update ``qa.git/include/release-qa.php`` with the appropriate information.
130   See the documentation within release-qa.php for more information, but all releases
131   and RCs are configured here. Only $QA_RELEASES needs to be edited.
132
133   Example: When rolling an RC, set the 'rc' with appropriate information for the
134   given version.
135
136   Note: Remember to update the MD5 checksum information.
137
1384. Update ``web/php.git/include/version.inc`` (x=major version number)
139
140 a. ``$PHP_x_RC`` = "5.4.0RC1"  (should be set to "false" before)
141
142 b. ``$PHP_x_RC_DATE`` = "06 September 2007"
143
1445. Commit and push those changes:
145
146 a. ``git commit -a && git push origin master``
147
1486. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the
149INSTALL and win32/install.txt files which are generated from the PHP manual sources.
150
151Rolling a stable release
152------------------------
153
1541. Checkout your release branch, you should have created when releasing previous RC
155and bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.
156
1572. If a CVE commit needs to be merged to the release, then have it committed to
158the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3,
159merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch.
160Don't forget to update NEWS manually in an extra commit then.
161
1623. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are
163still passing.
164
1654. run the "scripts/dev/credits" script in php-src and commit the changes in the
166credits files in ext/standard.
167
1685. Compile and make test, with and without ZTS, using the right Bison version
169(for example, for 5.5, Bison 2.4.1 is used)
170
1716. Check ./sapi/cli/php -v output for version matching.
172
1737. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``"
174
1758. Push the tag f.e. "``git push origin php-5.4.1``"
176
1779. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure
178and build three tarballs (gz, bz2 and xz).
179Check if the pear files are updated (phar).
180
18110. Generate the GPG signature files for the archives.
182  ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx``
183
18411. Commit and push all the tarballs and signature files to web/php-distributions.git,
185    then update the git submodule reference in web/php.git:
186    ``git submodule init;
187    git submodule update;
188    cd distributions;
189    git pull origin master;
190    cd ..;
191    git commit distributions;
192    git push;``
193This is to fetch the last commit id from php-distributions.git and commit this
194last commit id to web/php.git, then, mirrors will now sync
195
19612. Once the release has been tagged, contact release managers, windows builders, and package maintainers
197so that they can build releases. Do not send this announcement to any public lists.
198
199Getting the stable release announced
200------------------------------------
201
2021. Update phpweb/include/releases.inc with the old release info
203  (updates the download archives)
204
205 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the
206    highest branch, otherwise you have to do this manually, see point 1.b
207
208 b. In case multiple PHP minor versions are in active development you have
209    to manually copy the old information to include/releases.inc
210
2112. Edit ``phpweb/include/version.inc`` and change (X=major release number):
212
213 a. ``$PHP_X_VERSION`` to the correct version
214
215 b. ``$PHP_X_DATE`` to the release date
216
217 c. ``$PHP_X_MD5`` array and update all the md5 sums
218
219 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums
220
221 e. set ``$PHP_X_RC`` to false!
222
223 f. Make sure there are no outdated "notes" or edited "date" keys in the
224 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
225
226 g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")
227
2283. Create the release file (releases/x_y_z.php)
229   Usually we use the same content as for point 6, but included in php template
230   instead of the release xml.
231
2324. Update php-qa/include/release-qa.php and add the next version as an QARELEASE
233   (prepare for next RC)
234
2355. Update the ChangeLog file for the given major version
236f.e. ``ChangeLog-5.php`` from the NEWS file
237
238 a. go over the list and put every element on one line
239
240 b. check for &, < and > and escape them if necessary
241
242 c. remove all the names at the ends of lines
243
244 d. for marking up, you can do the following (with VI):
245
246  I. ``s/^- /<li>/``
247
248  II. ``s/$/<\/li>/``
249
250  III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``
251
252  IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``
253
254  V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/``
255
256  e. You may want to try php-web/bin/news2html to automate this task
257
2586. Add a short notice to phpweb stating that there is a new release, and
259highlight the major important things (security fixes) and when it is important
260to upgrade.
261
262 a. Call php bin/createNewsEntry in your local phpweb checkout
263
264 b. Add the content for the news entry
265
2667. **Check mirrors have been synced before announcing or pushing news**
267  Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror
268  Try several mirrors, mirrors may update slowly (may take an hour)
269
2708. Commit all the changes to their respective git repos
271
2729. Please note down the sha256 and the PGP signature (.asc). These *must* be
273   included in the release mail.
27410. Wait an hour or two, then send a mail to php-announce@lists.php.net,
275php-general@lists.php.net and internals@lists.php.net with a text similar to
276http://news.php.net/php.internals/17222.
277Please make sure that the mail to php-announce@ is its own completely separate email.
278This is to make sure that replies to the announcement on php-general@ or internals@
279will not accidentally hit the php-announce@ mailinglist.
280
281Re-releasing the same version (or -pl)
282--------------------------------------
283
2841. Commit the new binaries to ``phpweb/distributions/``
285
2862. Edit ``phpweb/include/version.inc`` and change (X=major release number):
287
288 a. If only releasing for one OS, make sure you edit only those variables
289
290 b. ``$PHP_X_VERSION`` to the correct version
291
292 c. ``$PHP_X_DATE`` to the release date
293
294 d. ``$PHP_X_MD5`` array and update all the md5 sums
295
296 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums
297
298 f. Make sure there are no outdated "notes" or edited "date" keys in the
299 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
300
3013. Add a short notice to phpweb stating that there is a new release, and
302highlight the major important things (security fixes) and when it is important
303to upgrade.
304
305 a. Call php bin/createNewsEntry in your local phpweb checkout
306
307 b. Add the content for the news entry
308
3094. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
310``archive/entries/YYYY-MM-DD-N.xml``)
311
3125. Wait an hour or two, then send a mail to php-announce@lists.php.net,
313php-general@lists.php.net and internals@lists.php.net with a text similar to
314the news entry.
315Please make sure that the mail to php-announce@ is its own completely separate email.
316This is to make sure that replies to the announcement on php-general@ or internals@
317will not accidentally hit the php-announce@ mailinglist.
318