source: macports-base/portmgr/ReleaseProcess.md

Last change on this file was 7eb7cffbd7985d9abda9dc4855e58c6aae33b37f, checked in by neverpanic (Clemens Lang), 2 months ago

ReleaseProcess: Drop Google+, it no longer exists

  • Property mode set to 100644
File size: 15.1 KB
Line 
1# MacPorts Release Process #
2
3This file documents the evolving MacPorts release process.
4
5
6## Goals of a Release ##
7
8There are several goals in the release process:
9
10*   Make a specific version of MacPorts available to users.
11*   Archive the materials (code, documentation, etc) that compose the release.
12*   Replicatability: enable the release to be regenerated.
13*   Consistency: codify naming, network locations, etc, for released
14    components.
15*   Ensure that the user base and public is notified of the release.
16
17
18## Steps to a Release ##
19
20The following steps to a release are documented in more detail below:
21
22*   Create a release branch to carry the release.
23*   Prepare the code for release.
24*   Tag the release.
25*   Create release products: tarballs and installers.
26*   Post release products.
27*   Make release version available through selfupdate.
28*   Notify public of the release.
29
30
31### Create a Release Branch ###
32
33For each major release (i.e. 1.9._x_, 2.0._x_, etc.) an appropriate branch is
34created with a consistent name. To do this, two things are required:
35
36*   Choose the git revision from which to create the branch, most likely based
37    off master.
38*   Create the branch (e.g. release-2.0) with git. The following commands
39    assume the remote "origin" points to macports/macports-base on GitHub.
40
41        git branch release-2.0 origin/master
42        git push origin release-2.0
43
44The actual release, alpha or beta releases, release candidates, and any point
45releases will all live on this branch. Releases of any kind will need to be
46tagged appropriately and point to commits on this branch.
47
48Only this base repository, not the ports tree kept in another repository, will
49be branched for a given release.
50
51Once master is to be used for development of the next major version, increase
52its version information to indicate it's moved past the release version by
53setting the patch-level version to 99, e.g. 2.0.99 in
54[`config/macports_version`][macports_version].
55
56
57### Prepare the code for Release ###
58
59In preparation for a release, several things should be completed within the
60code:
61
62*   Update the file [`ChangeLog`][ChangeLog] in both master and the release
63    branch to reflect the appropriate changes.
64*   Update the file [`config/macports_version`][macports_version] with the
65    target release number. The content of this file is recorded as the
66    MacPorts version at MacPorts build time, as displayed by the port command,
67    and it's also used by the selfupdate procedure to determine whether
68    a newer version of code is available. It should be different between
69    master and the release branch, the former greater to differentiate it from
70    the latter.
71*   Preserve [`config/mp_version`][mp_version] and
72    [`config/dp_version`][dp_version] at the 1.800 or 1.710 fixed values,
73    respectively, if selfupdate backwards compatibility with old MacPorts
74    installations is still desired. (see
75    https://trac.macports.org/changeset/43571/trunk/base or [ce8a77c][])
76*   Update the autoconf [`configure`][configure] script through the provided
77    [`autogen.sh`][autogen.sh] script once the version number in `mp_version`
78    has been changed, since the former reads the latter.
79*   Regenerate all man pages from scratch to ensure the new version number is
80    used in the output file. AsciiDoc and DocBook either need to be installed
81    in the target prefix or manually pass the correct paths if they are
82    installed elsewhere.
83
84        ./autogen.sh
85        ./standard_configure.sh
86        make -C doc/ clean all \
87            ASCIIDOC=/opt/local/bin/asciidoc \
88            XSLTPROC=/opt/local/bin/xsltproc \
89            DOCBOOK_XSL=/opt/local/share/xsl/docbook-xsl-nons/manpages/docbook.xsl
90
91*   Make sure that these and any other changes or bug fixes are made on and/or
92    merged between the release branch and master as needed. For instance, if
93    you've made changes to `ChangeLog` only on the release branch, those
94    changes should be merged back into master as well.
95
96
97### Tag the Release ###
98
99Once the release is ready, it must be tagged so that the release components
100may be fetched in the future, to ensure replicability. Generally, a release
101candidate is first tagged and built. When and if it is approved as the actual
102release, an additional tag is created that names the same sources.
103
104Tagging conventions:
105
106*   v2.0.0-beta2 (beta 2 for release 2.0.0)
107*   v2.0.0-rc1 (release candidate 1 for release 2.0.0)
108*   v2.0.0 (tagged release 2.0.0)
109*   v2.0.1 (2.0.1 release)
110
111We first create an annotated tag pointing to the release branch to make up the
112final release. Annotated tags preserve who made the tag and when. Additionally
113the tag should be signed with GPG by using the `-s` flag in order to allow
114later verification of the signature.
115
116    git tag -a -s v2.0.0 release-2.0
117    git push origin v2.0.0
118
119Although only base repository is branched and tagged for a given major
120release, we also create a separate tag in the ports tree at the time the final
121release tag is created for a major release (_x_._y_.0). This intends to provide
122a set of ports intended to work with that release.
123
124    git clone macports/macports-ports macports-ports
125    cd macports-ports
126    git tag -a -s v2.0.0-archive origin/master
127    git push origin v2.0.0-archive
128
129
130### Create & Post Release Tarballs ###
131
132The release tarballs are .tar.bz2 and .tar.gz archives of the base repository.
133They are named with the following naming convention:
134
135    MacPorts-2.0.0.tar.{bz2,gz} (base repository, corresponding to tag v2.0.0)
136
137The following commands issued to the top level Makefile will generate all the
138tarballs and checksums:
139
140    make dist DISTVER=2.0.0
141
142The release should be signed with a detached GPG signature in order to allow
143cryptographic verification. To do this automatically, use the additional
144argument `DISTGPGID` on the make command. The value specifies a key ID either
145in hexadecimal format or a email address matching exactly one key. For
146details, see [HOW TO SPECIFY A USER ID in gpg(1)][gpg-user-id] for details.
147
148    make dist DISTVER=2.0.0 DISTGPGID=<handle>@macports.org
149
150These tarballs and the checksums are uploaded to the
151https://distfiles.macports.org/MacPorts/ directory. At present, this must be
152done with the help of the infrastructure team.
153
154
155### Create Release Packages and Disk Image(s) ###
156
157The dmg is a macOS disk image that contains a standalone installer,
158configured in the usual way, named in a consistent fashion and incorporating
159the OS version for which it was built.
160
161For 10.6 and newer, we now build flat packages, so an enclosing dmg is not
162necessary.
163
164*   MacPorts-2.0.0-10.5-Leopard.dmg
165*   MacPorts-2.0.0-10.6-SnowLeopard.pkg
166*   MacPorts-2.0.0-10.7-Lion.pkg
167
168To create a pkg or dmg, use the MacPorts port. The Portfile will need to be
169updated to incorporate the proper release version and checksums, and the
170release tarballs will need to be already uploaded to the downloads section of
171the site (wherefrom the sources are fetched by the MacPorts port to build the
172pkg for the release). Make sure the ports tree you're using to build the pkgs
173is fully up to date.
174
175    sudo port -d pkg MacPorts
176    sudo port -d dmg MacPorts
177
178Name each pkg/dmg appropriately, and then sign the pkgs with a Developer ID
179(make sure to use the Installer certificate, not the Application one):
180
181    cd work
182    mv MacPorts-2.0.0.pkg unsigned/MacPorts-2.0.0-10.7-Lion.pkg
183    productsign --sign "Developer ID Installer: John Doe" unsigned/MacPorts-2.0.0-10.7-Lion.pkg MacPorts-2.0.0-10.7-Lion.pkg
184
185(Note that packages signed with Xcode 10 appear to be incompatible with
186Mac OS X 10.6.)
187
188For macOS 10.14 Mojave and later, the pkg should also be submitted for
189notarization after signing:
190
191    xcrun altool --notarize-app --primary-bundle-id org.macports.base \
192        --username <your-apple-id> --password @keychain:altool \
193        --file MacPorts-2.0.0-10.14-Mojave.pkg
194
195After notification of successful notarization is received:
196
197    xcrun stapler staple MacPorts-2.5.4-10.14-Mojave.pkg
198
199After signing (and notarizing if applicable), generate checksums, which will
200need to be added to the existing checksums file in the downloads directory:
201
202    for type in -md5 -sha1 -ripemd160 -sha256; do
203      openssl dgst $type MacPorts-2.0.0-*.{pkg,dmg} >> MacPorts-2.0.0.chk.txt
204    done
205
206These new products, along with the new checksums, also have to be posted to
207the appropriate directory of the MacPorts distfiles server. Developers are
208required to validate the generated installer as thoroughly as possible through
209extensive testing, which is mainly why this step of the release process is not
210automated through a Makefile target or similar. A good way of validating the
211installer is to first create the destroot of the port and examine it for:
212
213*   Linking: libraries and binaries should not be linked against anything
214    that's not present by default on a vanilla macOS installation +
215    developer tools, excluding even the MacPorts installation prefix; this can
216    be accomplished through the use of `otool -L`. Currently the libraries and
217    binaries in need of linking validation are:
218    *   `${destroot}/opt/local/bin/daemondo`
219    *   `${destroot}/opt/local/share/macports/Tcl/darwintrace1.0/darwintrace.dylib`
220    *   `${destroot}/opt/local/share/macports/Tcl/macports1.0/MacPorts.dylib`
221    *   `${destroot}/opt/local/share/macports/Tcl/pextlib1.0/Pextlib.dylib`
222    *   `${destroot}/opt/local/share/macports/Tcl/registry2.0/registry.dylib`
223*   Universal building: All the files that need linking confirmation in the
224    step above also need to be confirmed to be universal (i386/ppc on 10.5 and
225    earlier, i386/x86_64 on 10.6 and later). A way to do this is with the
226    `file(1)` command:
227
228        $ file ${destroot}/opt/local/bin/daemondo:
229        ${destroot}/opt/local/bin/daemondo: Mach-O universal binary with 2 architectures
230        ${destroot}/opt/local/bin/daemondo (for architecture ppc):  Mach-O executable ppc
231        ${destroot}/opt/local/bin/daemondo (for architecture i386): Mach-O executable i386
232
233*   tclsh invocation: all scripts installed in `${destroot}/opt/local/bin`
234    should invoke the tclsh shell through a call like:
235
236        #!/opt/local/bin/port-tclsh
237
238    thus ensuring that our bundled Tcl interpreter is used in our scripts.
239*   Miscellaneous: anything else that might seem out of the ordinary for
240    a fully default-configured MacPorts installation.
241
242Once the above requirements have been positively asserted, the one remaining
243test is to make sure that the dmg mounts in the Finder when double-clicked,
244and that the pkg contained therein properly starts up Installer.app when it's
245double-clicked.
246
247
248### Create Release on GitHub ###
249
250All of our distfiles should also be available as downloads from a new GitHub
251release. Create a new release matching the previously created tag on GitHub
252and attach all tarballs and installers to it.
253
254
255### Make the Release Available through Self-Update ###
256
257In order to make the release version available through selfupdate, the
258[`config/RELEASE_URL`][RELEASE_URL] file in the base repository needs to be
259updated with the tag of the release to distribute. This file is read by the
260cron job that makes the code available via rsync. See
261[`jobs/mprsyncup`][mprsyncup] in the macports-infrastructure repository.
262
263
264### Make the Release Available for Pull Request Checks on Travis CI ###
265
266To make the new release available for testing pull requests on
267[Travis CI](https://travis-ci.org/macports), update the travis-ci branch by
268merging the newly tagged release into it.
269
270    $ git checkout travis-ci
271    $ git merge v2.0.0
272    $ git push origin travis-ci
273
274Verify that the new release has been built and deployed successfully on
275[Travis CI](https://travis-ci.org/macports/macports-base/branches).
276
277
278### Update the branch buildbot uses to generate manpages ###
279
280When releasing a new major version, you should update the buildbot's
281[`master.cfg` file][buildbot-master-cfg] so that the single branch scheduler
282for the manpage jobs pulls from that new branch. To do that, look for `'man'
283in config['deploy']`, locate the `util.ChangeFilter` object passed to the
284constructor of `schedulers.SingleBranchScheduler` below that and adjust the
285`branch` parameter to the branch you are releasing. Notify ryandesign@ to have
286this change deployed on the buildbot.
287
288
289### Add Release Version to Trac ###
290
291Add the new version to the list of released versions on Trac. Edit the list
292using the [web admin interface](https://trac.macports.org/admin/ticket/versions)
293on our Trac installation.
294
295
296### Verify That the Public Rsync Server Has Updated ###
297
298Verify that the MacPorts version on the public rsync server has been updated:
299
300    $ curl -s http://nue.de.rsync.macports.org/macports/release/base/config/macports_version
301
302
303### Notify the Public of the Release ###
304
305Once the release has been posted, notification of the release should be
306sent/posted to the following places:
307
308*   The [macports-announce][]@, [macports-users][]@ and [macports-dev][]@
309    mailing lists.
310*   The MacPorts website, by adapting the `$macports_version_major` and
311    `$macports_version_latest` variables as appropriate in the
312    [`includes/common.inc`][common.inc] file in the macports-www repository.
313*   The [news section][news] of the website (see the [macports.github.io][]
314    repository)
315*   The `&macports-version;` entity in
316    [`guide/xml/installing.xml`][installing.xml] and
317    [`guide/xml/using.xml`][using.xml] in the guide repository.
318*   External websites
319    *   [SourceForge][]
320        (submitter: portmgr@)
321    *   [MacUpdate][]
322        (submitter: ???)
323    *   [Twitter][]
324        (submitter: raimue@)
325    *   (Where else?)
326
327
328### Use of new features in Portfiles ###
329
330Using new features introduced by a release should be delayed for 14 days until
331being deployed in the ports tree. This should allow users to upgrade their
332installations to the new release. This delay matches the warning about
333outdated ports tree sources.
334
335
336[autogen.sh]: /autogen.sh
337[ce8a77c]: https://github.com/macports/macports-base/commit/ce8a77c858c679f2d7627a3cd613436b2ead82e7
338[ChangeLog]: /ChangeLog
339[common.inc]: https://github.com/macports/macports-www/blob/master/includes/common.inc
340[configure]: /configure
341[dp_version]: /config/dp_version
342[gpg-user-id]: https://gnupg.org/documentation/manuals/gnupg/Specify-a-User-ID.html
343[installing.xml]: https://github.com/macports/macports-guide/blob/master/guide/xml/installing.xml
344[macports-announce]: mailto:macports-announce@lists.macports.org
345[macports-dev]: mailto:macports-dev@lists.macports.org
346[macports-users]: mailto:macports-users@lists.macports.org
347[macports.github.io]: https://github.com/macports/macports.github.io
348[macports_version]: /config/macports_version
349[MacUpdate]: https://www.macupdate.com/app/mac/21309/macports
350[mp_version]: /config/mp_version
351[mprsyncup]: https://github.com/macports/macports-infrastructure/blob/master/jobs/mprsyncup
352[news]: https://www.macports.org/news
353[RELEASE_URL]: /config/RELEASE_URL
354[SourceForge]: http://sourceforge.net/projects/macports
355[Twitter]: http://twitter.com/macports
356[using.xml]: https://github.com/macports/macports-guide/blob/master/guide/xml/using.xml
357[buildbot-master-cfg]: https://github.com/macports/macports-infrastructure/blob/master/buildbot/master.cfg
358
359<!-- vim:set fenc=utf-8 ft=markdown tw=78 et sw=4 sts=4: -->
Note: See TracBrowser for help on using the repository browser.