xref: /PHP-5.5/README.RELEASE_PROCESS (revision 983f155e)
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 bases 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 acces 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. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a
97directory "downloads/". Copy them into there, so that the system can generate
98MD5 sums. If you do not have this directory, talk to Derick or Dan.
99
10014. Now the RC can be found on http://downloads.php.net/yourname,
101f.e. http://downloads.php.net/derick/
102
10315. Once the release has been tagged, contact the PHP Windows development team
104(internals-win@lists.php.net) so that Windows binaries can be created. Once
105those are made, they should be placed into the same directory as the source snapshots.
106
107Getting the non stable release (alpha/beta/RC) announced
108--------------------------------------------------------
109
1101. Send an email (see example here: http://news.php.net/php.internals/19486)
111**To** ``internals@lists.php.net`` and ``php-general@lists.php.net`` lists
112pointing out "the location of the release" and "the possible release date of
113either the next RC, or the final release".
114
1152. 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``.
117This email is to notify the selected projects about a new release so that they
118can make sure their projects keep working. Make sure that you have been setup
119as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan,
120Derick) run the following commands for you:
121
122``ssh lists.php.net``
123
124``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``
125
1263. Update ``qa.git/include/release-qa.php`` with the appropriate information.
127   See the documentation within release-qa.php for more information, but all releases
128   and RCs are configured here. Only $QA_RELEASES needs to be edited.
129
130   Example: When rolling an RC, set the 'rc' with appropriate information for the
131   given version.
132
133   Note: Remember to update the MD5 checksum information.
134
1354. 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 b. ``$PHP_x_RC_DATE`` = "06 September 2007"
140
1415. Commit and push those changes:
142
143 a. ``git commit -a && git push origin master``
144
1456. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the
146INSTALL and win32/install.txt files which are generated from the PHP manual sources.
147
148Rolling a stable release
149------------------------
150
1511. Checkout your release branch, you should have created when releasing previous RC
152and bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.
153
1542. If a CVE commit needs to be merged to the release, then have it committed to
155the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3,
156merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch.
157Don't forget to update NEWS manually in an extra commit then.
158
1593. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are
160still passing.
161
1624. run the "scripts/dev/credits" script in php-src and commit the changes in the
163credits files in ext/standard.
164
1655. Compile and make test, with and without ZTS, using the right Bison version
166(for example, for 5.5, Bison 2.4.1 is used)
167
1686. Check ./sapi/cli/php -v output for version matching.
169
1707. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``"
171
1728. Push the tag f.e. "``git push origin php-5.4.1``"
173
1749. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure
175and build three tarballs (gz, bz2 and xz).
176Check if the pear files are updated (phar).
177
17810. Generate the GPG signature files for the archives.
179  ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx``
180
18111. Commit and push all the tarballs and signature files to web/php-distributions.git,
182    then update the git submodule reference in web/php.git:
183    ``git submodule init;
184    git submodule update;
185    cd distributions;
186    git pull origin master;
187    cd ..;
188    git commit distributions;
189    git push;``
190This is to fetch the last commit id from php-distributions.git and commit this
191last commit id to web/php.git, then, mirrors will now sync
192
19312. Once the release has been tagged, contact the PHP Windows development team
194(internals-win@lists.php.net) so that Windows binaries can be created.
195
196Getting the stable release announced
197------------------------------------
198
1991. Update phpweb/include/releases.inc with the old release info
200  (updates the download archives)
201
202 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the
203    highest branch, otherwise you have to do this manually, see point 1.b
204
205 b. In case multiple PHP minor versions are in active development you have
206    to manually copy the old information to include/releases.inc
207
2082. Edit ``phpweb/include/version.inc`` and change (X=major release number):
209
210 a. ``$PHP_X_VERSION`` to the correct version
211
212 b. ``$PHP_X_DATE`` to the release date
213
214 c. ``$PHP_X_MD5`` array and update all the md5 sums
215
216 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums
217
218 e. set ``$PHP_X_RC`` to false!
219
220 f. Make sure there are no outdated "notes" or edited "date" keys in the
221 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
222
223 g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")
224
2253. Create the release file (releases/x_y_z.php)
226   Usually we use the same content as for point 6, but included in php template
227   instead of the release xml.
228
2294. Update php-qa/include/release-qa.php and add the next version as an QARELEASE
230   (prepare for next RC)
231
2325. Update the ChangeLog file for the given major version
233f.e. ``ChangeLog-5.php`` from the NEWS file
234
235 a. go over the list and put every element on one line
236
237 b. check for &, < and > and escape them if necessary
238
239 c. remove all the names at the ends of lines
240
241 d. for marking up, you can do the following (with VI):
242
243  I. ``s/^- /<li>/``
244
245  II. ``s/$/<\/li>/``
246
247  III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``
248
249  IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``
250
251  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
2556. Add a short notice to phpweb stating that there is a new release, and
256highlight the major important things (security fixes) and when it is important
257to upgrade.
258
259 a. Call php bin/createNewsEntry in your local phpweb checkout
260
261 b. Add the content for the news entry
262
2637. **Check mirrors have been synced before announcing or pushing news**
264  Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror
265  Try several mirrors, mirrors may update slowly (may take an hour)
266
2678. Commit all the changes to their respective git repos
268
2699. Wait an hour or two, then send a mail to php-announce@lists.php.net,
270php-general@lists.php.net and internals@lists.php.net with a text similar to
271http://news.php.net/php.internals/17222.
272Please make sure that the mail to php-announce@ is its own completely seperate email.
273This is to make sure that repiles to the announcement on php-general@ or internals@
274will not accidentally hit the php-announce@ mailinglist.
275
276Re-releasing the same version (or -pl)
277--------------------------------------
278
2791. Commit the new binaries to ``phpweb/distributions/``
280
2812. Edit ``phpweb/include/version.inc`` and change (X=major release number):
282
283 a. If only releasing for one OS, make sure you edit only those variables
284
285 b. ``$PHP_X_VERSION`` to the correct version
286
287 c. ``$PHP_X_DATE`` to the release date
288
289 d. ``$PHP_X_MD5`` array and update all the md5 sums
290
291 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums
292
293 f. Make sure there are no outdated "notes" or edited "date" keys in the
294 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
295
2963. Add a short notice to phpweb stating that there is a new release, and
297highlight the major important things (security fixes) and when it is important
298to upgrade.
299
300 a. Call php bin/createNewsEntry in your local phpweb checkout
301
302 b. Add the content for the news entry
303
3044. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
305``archive/entries/YYYY-MM-DD-N.xml``)
306
3075. Wait an hour or two, then send a mail to php-announce@lists.php.net,
308php-general@lists.php.net and internals@lists.php.net with a text similar to
309the news entry.
310Please make sure that the mail to php-announce@ is its own completely seperate email.
311This is to make sure that repiles to the announcement on php-general@ or internals@
312will not accidentally hit the php-announce@ mailinglist.
313