README.RELEASE_PROCESS 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372
  1. =======================
  2. PHP Release Process
  3. =======================
  4. General notes and tips
  5. ----------------------
  6. 1. Do not release on Fridays, Saturdays or Sundays
  7. because the sysadmins can not upgrade stuff then.
  8. 2. Package two days before a release. So if the release is to be on Thursday,
  9. package on Tuesday. Think about timezones as well.
  10. 3. Ensure that the tests on Travis CI are green.
  11. See: https://travis-ci.org/php/php-src/builds
  12. It is recommended to do so a couple of days before the packaging day, to
  13. have enough time to investigate failures, communicate with the authors and
  14. commit the fixes.
  15. The RM for the branch is also responsible for keeping the CI green on
  16. ongoing basis between the releases. Check the CI status for your branch
  17. periodically and resolve the failures ASAP. See more in:
  18. https://wiki.php.net/rfc/travis_ci
  19. 4. Ensure that Windows builds will work before packaging
  20. 5. Follow all steps to the letter. When unclear ask previous RM's (David/Julien/
  21. Johannes/Stas/Derick/Ilia) before proceeding. Ideally make sure that for the
  22. first releases one of the previous RM's is around to answer questions. For the
  23. steps related to the php/QA/bug websites try to have someone from the webmaster
  24. team (Bjori) on hand.
  25. 6. Verify the tags to be extra sure everything was tagged properly.
  26. 7. Moving extensions from/to PECL requires write access to the destination.
  27. Most developers should have this.
  28. Moving extensions from php-src to PECL
  29. - Checkout the pecl directory, most likely you want a sparse-root checkout
  30. svn co --depth=empty https://svn.php.net/repository/pecl
  31. - Create a directory for the extension incl. branch and tag structure,
  32. no trunk at this point and commit this to svn
  33. cd pecl; mkdir foo foo/tags foo/branches; svn add foo; svn commit
  34. - Move the extension from php-src to the new location
  35. svn mv https://svn.php.net/repository/php/php-src/trunk/ext/foo \
  36. https://svn.php.net/repository/pecl/foo/trunk
  37. If the extension is still usable or not dead, in cooperation with the extension
  38. maintainers if any:
  39. - create the pecl.php.net/foo package and its content, license, maintainer
  40. - create the package.xml, commit
  41. - release the package
  42. For Moving extensions from PECL to php-src the svn mv has to be done the other
  43. way round.
  44. Rolling a non stable release (alpha/beta/RC)
  45. --------------------------------------------
  46. 1. Check windows snapshot builder logs (http://windows.php.net/downloads/snaps/ the last revision)
  47. 2. Check the tests at https://travis-ci.org/php/php-src/builds
  48. 3. run the "scripts/dev/credits" script in php-src and commit the changes in the
  49. credits files in ext/standard.
  50. 4. Checkout the release branch for this release (e.g., PHP-5.4.2) from the main branch.
  51. 5. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``.
  52. Do not use abbreviations for alpha and beta. Do not use dashes, you should
  53. ``#define PHP_VERSION "5.4.22RC1"`` and not ``#define PHP_VERSION "5.4.22-RC1"``
  54. 6. Compile and make test, with and without ZTS, using the right Bison version
  55. (for example, for 5.5, Bison 2.4.1 is used)
  56. 7. Check ./sapi/cli/php -v output for version matching.
  57. 8. If all is right, commit the changes to the release branch with ``git commit -a``.
  58. 9. Tag the repository release branch with the version, e.g.:
  59. ``git tag -u YOURKEYID php-5.4.2RC2``
  60. 10. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and ``NEWS``
  61. in the *main* branch (PHP-5.4 for example) to prepare for the **next** version.
  62. F.e. if the RC is "5.4.1RC1" then the new one should be "5.4.2-dev" - regardless if we get
  63. a new RC or not. This is to make sure ``version_compare()`` can correctly work.
  64. Commit the changes to the main branch.
  65. 11. Push the changes to the main repo, the tag, the main branch and the release branch :
  66. ``git push --tags origin HEAD``
  67. ``git push origin {main branch}``
  68. ``git push origin {release branch}``
  69. 12. run: ``PHPROOT=. ./makedist 5.4.2RC2``, this will export the tree, create configure
  70. and build three tarballs (gz, bz2 and xz).
  71. 13. run ``scripts/dev/gen_verify_stub <version> [identity]``, this will sign the tarballs
  72. and output verification information to be included in announcement email
  73. 14. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a
  74. directory "public_html/". Copy them into there, so that the system can generate
  75. MD5 sums. If you do not have this directory, create it.
  76. 15. Now the RC can be found on http://downloads.php.net/~yourname,
  77. f.e. http://downloads.php.net/~derick/
  78. 16. Once the release has been tagged, contact the release-managers@ distribution list
  79. so that Windows binaries can be created. Once those are made, they can be found at
  80. http://windows.php.net/download
  81. Getting the non stable release (alpha/beta/RC) announced
  82. --------------------------------------------------------
  83. 1. Update ``qa.git/include/release-qa.php`` with the appropriate information.
  84. See the documentation within release-qa.php for more information, but all releases
  85. and RCs are configured here. Only $QA_RELEASES needs to be edited.
  86. Example: When rolling an RC, set the 'rc' with appropriate information for the
  87. given version.
  88. Note: Remember to update the MD5 and sha256 checksum information.
  89. 2. Update ``web/php.git/include/version.inc`` (x=major version number)
  90. a. ``$PHP_x_RC`` = "5.4.0RC1" (should be set to "false" before)
  91. b. ``$PHP_x_RC_DATE`` = "06 September 2007"
  92. 3. Add a short notice to phpweb stating that there is a new release, and
  93. highlight the major important things (security fixes) and when it is important
  94. to upgrade.
  95. a. Call php bin/createNewsEntry in your local phpweb checkout
  96. Use category "releases" for all stable releases.
  97. Use category "frontpage" for X.Y.0 non-stable releases only (news only).
  98. b. Add the content for the news entry. Be sure to include the text:
  99. "THIS IS A DEVELOPMENT PREVIEW - DO NOT USE IT IN PRODUCTION!"
  100. 4. Commit and push changes to qa and web
  101. *Wait for web and qa sites to update with new information before sending announce*
  102. 5. Send **separate** emails **To** ``internals@lists.php.net`` and ``php-general@lists.php.net``
  103. lists pointing out "the location of the release" and "the possible release date of
  104. either the next RC, or the final release". Include in this information the verification
  105. information output by ``gen_verify_stub``.
  106. 6. Send **separate** emails (see example here http://news.php.net/php.pear.qa/5201) **To**
  107. ``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``.
  108. These emails are to notify the selected projects about a new release so that they
  109. can make sure their projects keep working. Make sure that you have been setup
  110. as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan,
  111. Derick) run the following commands for you:
  112. ``ssh lists.php.net``
  113. ``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``
  114. Rolling a stable release
  115. ------------------------
  116. 1. Checkout your release branch, you should have created when releasing previous RC
  117. and bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``.
  118. 2. If a CVE commit needs to be merged to the release, then have it committed to
  119. the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3,
  120. merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch.
  121. Don't forget to update NEWS manually in an extra commit then.
  122. 3. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are
  123. still passing.
  124. 4. run the "scripts/dev/credits" script in php-src and commit the changes in the
  125. credits files in ext/standard.
  126. 5. Compile and make test, with and without ZTS, using the right Bison version
  127. (for example, for 5.5, Bison 2.4.1 is used)
  128. 6. Check ./sapi/cli/php -v output for version matching.
  129. 7. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``"
  130. 8. Push the tag f.e. "``git push origin php-5.4.1``"
  131. 9. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure
  132. and build three tarballs (gz, bz2 and xz).
  133. Check if the pear files are updated (phar).
  134. On some systems the behavior of GNU tar can default to produce POSIX compliant archives
  135. with PAX headers. As not every application is compatible with that format, creation of
  136. archives with PAX headers should be avoided. When packaging on such a system, the GNU tar
  137. can be influenced by defining the environment variable TAR_OPTIONS='--format=gnu'.
  138. 10. Generate the GPG signature files for the archives.
  139. ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx``
  140. 11. Commit and push all the tarballs and signature files to web/php-distributions.git,
  141. then update the git submodule reference in web/php.git:
  142. ``git submodule init;
  143. git submodule update;
  144. cd distributions;
  145. git fetch;
  146. git pull --rebase origin master;
  147. cd ..;
  148. git commit distributions;
  149. git push;``
  150. This is to fetch the last commit id from php-distributions.git and commit this
  151. last commit id to web/php.git, then, mirrors will now sync
  152. 12. Once the release has been tagged, contact release managers, windows builders, and package maintainers
  153. so that they can build releases. Do not send this announcement to any public lists.
  154. Getting the stable release announced
  155. ------------------------------------
  156. 1. Update phpweb/include/releases.inc with the old release info
  157. (updates the download archives)
  158. a. You can run ``php bin/bumpRelease 5`` if you are making a release for the
  159. highest branch, otherwise you have to do this manually, see point 1.b
  160. b. In case multiple PHP minor versions are in active development you have
  161. to manually copy the old information to include/releases.inc
  162. 2. Edit ``phpweb/include/version.inc`` and change (X=major release number):
  163. a. ``$PHP_X_VERSION`` to the correct version
  164. b. ``$PHP_X_DATE`` to the release date
  165. c. ``$PHP_X_MD5`` array and update all the md5 sums
  166. d. ``$PHP_X_SHA256`` array and update all the SHA256 sums
  167. e. set ``$PHP_X_RC`` to false!
  168. f. Make sure there are no outdated "notes" or edited "date" keys in the
  169. ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
  170. g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")
  171. 3. Create the release file (releases/x_y_z.php)
  172. Usually we use the same content as for point 6, but included in php template
  173. instead of the release xml.
  174. 4. Update php-qa/include/release-qa.php and add the next version as an QARELEASE
  175. (prepare for next RC)
  176. 5. Update the ChangeLog file for the given major version
  177. f.e. ``ChangeLog-5.php`` from the NEWS file
  178. a. go over the list and put every element on one line
  179. b. check for &, < and > and escape them if necessary
  180. c. remove all the names at the ends of lines
  181. d. for marking up, you can do the following (with VI):
  182. I. ``s/^- /<li>/``
  183. II. ``s/$/<\/li>/``
  184. III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``
  185. IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``
  186. V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/``
  187. e. You may want to try php-web/bin/news2html to automate this task
  188. 6. Add a short notice to phpweb stating that there is a new release, and
  189. highlight the major important things (security fixes) and when it is important
  190. to upgrade.
  191. a. Call php bin/createNewsEntry in your local phpweb checkout
  192. b. Add the content for the news entry
  193. 7. **Check mirrors have been synced before announcing or pushing news**
  194. Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror
  195. Try several mirrors, mirrors may update slowly (may take an hour)
  196. 8. Commit all the changes to their respective git repos
  197. 9. Please note down the sha256 and the PGP signature (.asc). These *must* be
  198. included in the release mail.
  199. 10. Wait an hour or two, then send a mail to php-announce@lists.php.net,
  200. php-general@lists.php.net and internals@lists.php.net with a text similar to
  201. http://news.php.net/php.internals/17222.
  202. Please make sure that the mail to php-announce@ is its own completely separate email.
  203. This is to make sure that replies to the announcement on php-general@ or internals@
  204. will not accidentally hit the php-announce@ mailinglist.
  205. Re-releasing the same version (or -pl)
  206. --------------------------------------
  207. 1. Commit the new binaries to ``phpweb/distributions/``
  208. 2. Edit ``phpweb/include/version.inc`` and change (X=major release number):
  209. a. If only releasing for one OS, make sure you edit only those variables
  210. b. ``$PHP_X_VERSION`` to the correct version
  211. c. ``$PHP_X_DATE`` to the release date
  212. d. ``$PHP_X_MD5`` array and update all the md5 sums
  213. e. ``$PHP_X_SHA256`` array and update all the SHA256 sums
  214. f. Make sure there are no outdated "notes" or edited "date" keys in the
  215. ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
  216. 3. Add a short notice to phpweb stating that there is a new release, and
  217. highlight the major important things (security fixes) and when it is important
  218. to upgrade.
  219. a. Call php bin/createNewsEntry in your local phpweb checkout
  220. b. Add the content for the news entry
  221. 4. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
  222. ``archive/entries/YYYY-MM-DD-N.xml``)
  223. 5. Wait an hour or two, then send a mail to php-announce@lists.php.net,
  224. php-general@lists.php.net and internals@lists.php.net with a text similar to
  225. the news entry.
  226. Please make sure that the mail to php-announce@ is its own completely separate email.
  227. This is to make sure that replies to the announcement on php-general@ or internals@
  228. will not accidentally hit the php-announce@ mailinglist.
  229. Forking a new release branch
  230. ----------------------------
  231. 1. One week prior to cutting X.Y.0beta1, warn internals@ that your version's branch
  232. is about to be cut, and that PHP-X.Y will be moving into feature freeze.
  233. Try to be specific about when the branch will be cut.
  234. Example: http://news.php.net/php.internals/99864
  235. 2. Just prior to cutting X.Y.0beta1, create the new branch locally.
  236. Add a commit on master after the branch point clearing the NEWS file, and updating
  237. main/php_versions.h and Zend/zend.h to update versions.
  238. Example: https://github.com/php/php-src/commit/5230541ef59e0637d5522293a7d099bf18ce6af3
  239. Push the new branch and the commit just added to master.
  240. 3. Immediately notify internals@ of the branch cut and advise the new merging order:
  241. Example: http://news.php.net/php.internals/99903
  242. 4. Update php-web:git.php and wiki.php.net/vcs/gitworkflow to reflect the new branch:
  243. Example: https://github.com/php/web-php/commit/74bcad4c770d95f21b7fbeeedbd76d943bb83f23
  244. 5. Notify nlopess@ to add PHP_X_Y tag to gcov.php.net
  245. New Release Manager Checklist
  246. -----------------------------
  247. 1. Email systems@ to get setup for access to downloads.php.net and to be added to the
  248. release-managers@ distribution list.
  249. 2. Create a GPG key for your @php.net address and publish it by editing `include/gpg-keys.inc`
  250. in the `web-php` repository, adding the output of `gpg --fingerprint "$USER@php.net"`. Let
  251. one or more of the previous RMs sign your key. Publish your public key to pgp.mit.edu with:
  252. `gpg --keyserver pgp.mit.edu --send-keys $KEYID`
  253. 3. Request karma to edit main/php_version.h. Possibly karma for other restricted parts of
  254. php-src might come in question.
  255. 4. Request karma for web/qa.git and web/php.git for publishing release announcements.
  256. 5. Request moderation access to announce@php.net and primary-qa-tester@lists.php.net lists, to
  257. be able to moderate your release announcements. All the announcements should be sent from
  258. the @php.net alias.