source: trunk/base/portmgr/ReleaseProcess @ 139170

Last change on this file since 139170 was 121450, checked in by jmr@…, 6 years ago

update ReleaseProcess, freecode no longer accepts submissions

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 12.7 KB
Line 
1
2= MacPorts Release Process =
3
4This file documents the evolving MacPorts release process.
5$Id: ReleaseProcess 121450 2014-06-25 22:33:13Z jmr@macports.org $
6
7
8== Goals of a Release ==
9
10There are several goals in the release process:
11
12 * Make a specific version of MacPorts available to users.
13 * Archive the materials (code, documentation, etc) that compose the release.
14 * Replicatability: enable the release to be regenerated.
15 * Consistency: codify naming, network locations, etc, for released components.
16 * Ensure that the user base and public is notified of the release.
17
18
19== Steps to a Release ==
20
21The following steps to a release are documented in more detail below:
22
23 * Create an svn branch to carry the release.
24 * Prepare the code for release.
25 * Tag the release.
26 * Create release products: tarballs and dmgs.
27 * Post release products.
28 * Make release version available through selfupdate.
29 * Notify public of the release.
30
31
32=== Create a Release Branch ===
33
34For each major release (i.e. 1.9.x, 2.0.x, etc.) an appropriate branch is created with a
35consistent name. To do this, two things are required:
36
37 * Choose the svn revision from which to create the branch, most likely based off trunk.
38 * Create the branch (e.g. release_2_0) through the svn "copy" command for history preservation,
39   first creating the needed branch directory to preserve the required directory structure
40   (the 'base' directory level *needs* to exist in each release branch, otherwise selfupdate breaks):
41
42 svn mkdir -m "commit-message" https://svn.macports.org/repository/macports/branches/release_2_0
43 svn cp [-r<rev>] -m "commit-message" https://svn.macports.org/repository/macports/trunk/base \
44     https://svn.macports.org/repository/macports/branches/release_2_0
45
46The actual release, alpha or beta releases, release candidates, and any point releases will all
47live on this branch, and tagged appropriately and if necessary (a must for the actual releases,
48optional for beta snapshots) into the /tags svn directory.
49
50Only the base subdirectory, not the ports subdirectory, is branched for a given release.
51
52It is strongly recommended to use the latest version of the subversion port so that merge
53tracking information can be maintained between release branches and trunk/base if you intend
54to merge revisions back and forth between them, which is a very likely scenario.
55
56
57=== Prepare the code for Release ===
58
59In preparation for a release, several things should be completed within the code:
60
61 * Update the file base/ChangeLog in both trunk and the release branch to reflect the appropriate changes.
62 * Update the file base/config/macports_version with the target release number. The content of this file
63   is recorded as the MacPorts version at MacPorts build time, as displayed by the port command, and it's
64   also used by the selfupdate procedure to determine whether a newer version of code is available.
65   It should be different between trunk and the release branch, the former greater to differentiate it from
66   the latter.
67 * Preserve the file base/config/mp_version at the 1.800 fixed value if selfupdate backwards compatibility
68   with pre 1.8.0 MacPorts installations is still desired (cf. svn's r43571).
69 * Update the autoconf 'configure' script through the provided base/regen.sh script once the version number
70   in mp_version has been changed, since the former reads the latter.
71 * Make sure that these and any other changes or bug fixes are made on and/or merged between the release branch
72   and trunk as needed. For instance, if you've made changes to ChangeLog only on the release branch,
73   those changes should be merged back into trunk as well.
74
75
76=== Tag the Release ===
77
78Once the release is ready, it must be tagged so that the release components may be fetched in the future,
79to ensure replicability. Generally, a release candidate is first tagged and built. When and if it is
80approved as the actual release, an additional tag is created that names the same sources.
81
82Tagging conventions:
83
84 * release_2_0_0-beta2 (beta 2 for release 2.0.0)
85 * release_2_0_0-rc1 (release candidate 1 for release 2.0.0)
86 * release_2_0_0 (tagged release 2.0.0)
87 * release_2_0_0-archive (tagged release 2.0.0 -- complete archive)
88 * release_2_0_1 (2.0.1 release)
89
90We first tag the branched base directory to make up the final release:
91
92 svn cp -m "commit-message" https://svn.macports.org/repository/macports/branches/release_2_0 \
93     https://svn.macports.org/repository/macports/tags/release_2_0_0
94
95Although only the base subdirectory is branched and tagged for a given major release, we also create a
96separate tag for the entire tree (base sources and full ports tree) at the time the final release tag is
97created (only for major releases, x.y.0), in order to provide a stake in the ground that specifies a set
98of ports intended to work with that release. Note that this tag incorporates the entire svn trunk directory
99at the revision number at which the final release was tagged.
100
101The necessary working copy to create such a tag is created by checking out all of trunk at the specific
102revision of the final tagging of base and then switching the base directory to the appropriate release
103tag URL. For instance:
104
105 svn co [-r<rev>] https://svn.macports.org/repository/macports/trunk release_2.0.0-archive
106 cd release_2.0.0-archive
107 svn rm base
108 svn cp https://svn.macports.org/repository/macports/tags/release_2_0_0/base base
109
110And finally we tag the entire directory as release_2_0_0-archive:
111
112 cd ..
113 svn cp -m "commit-message" release_2.0.0-archive https://svn.macports.org/repository/macports/tags/release_2_0_0-archive
114
115
116=== Create & Post Release Tarballs ===
117
118The release tarballs are tar.bz2 and tar.gz archives of the base directory only and of the entire svn tree
119for a particular release. They are named with the following naming convention:
120
121 MacPorts-2.0.0.tar.{bz2,gz} (base directory only, corresponding to tag release_2_0_0)
122 MacPorts-2.0.0-archive.tar.{bz2,gz} (complete archives corresponding to tag release_2_0_0-archive)
123
124The following commands issued to the top level Makefile will generate all the tarballs and checksums:
125
126 make ARC=yes DISTVER=2.0.0 distfromsvn
127
128Note that if you omit the "ARC=yes" flag at the start of the make call then the full archive tarballs will not be produced.
129
130All these tarballs are uploaded to the http://distfiles.macports.org/MacPorts/ directory. At present, this must
131be done with the help of the MacOSForge sysadmin.
132
133Additionally, a file is created, and posted to the same location, that contains md5, sha1, rmd160, and sha256 checksums
134for each of the files:
135
136 MacPorts-2.0.0.chk.txt
137 (We should have a way to sign these checksums, and have the signer's keys posted somewhere.
138 Security experts in the project, would you be interested in leading this effort? Eric? Mark? Anyone else?)
139
140
141=== Create Release Packages and Disk Image(s) ===
142
143The dmg is a Mac OS X disk image that contains a standalone installer, configured in the usual way, for major
144MacPorts releases (x.y.0), named in a consistent fashion and incorporating the OS version for which it
145was built.
146
147For 10.6 and newer, we now build flat packages, so an enclosing dmg is not necessary.
148
149 MacPorts-2.0.0-10.5-Leopard.dmg
150 MacPorts-2.0.0-10.6-SnowLeopard.pkg
151 MacPorts-2.0.0-10.7-Lion.pkg
152
153To create a pkg or dmg, use the MacPorts port. The Portfile will need to be updated to incorporate the
154proper release version and checksums, and the release tarballs will need to be already uploaded to the
155downloads section of the site (wherefrom the sources are fetched by the MacPorts port to build the pkg
156for the release). Make sure the ports tree you're using to build the pkgs is fully up to date.
157
158 sudo port -d pkg MacPorts
159 sudo port -d dmg MacPorts
160
161Name each pkg/dmg appropriately, and then sign the pkgs with a Developer ID (make sure to use the
162Installer certificate, not the Application one):
163
164 cd work
165 mv MacPorts-2.0.0.pkg unsigned/MacPorts-2.0.0-10.7-Lion.pkg
166 productsign --sign "Developer ID Installer: John Doe" unsigned/MacPorts-2.0.0-10.7-Lion.pkg MacPorts-2.0.0-10.7-Lion.pkg
167
168After signing, generate checksums, which will need to be added to the existing checksums
169file in the downloads directory:
170
171 for pkg in MacPorts-2.0.0-*.{pkg,dmg}; do for type in -md5 -sha1 -ripemd160 -sha256; do openssl dgst $type $pkg; done >> MacPorts-2.0.0.chk.txt; done
172
173These new products, along with the new checksums, also have to be posted to the appropriate
174directory of the MacPorts distfiles server. Developers are required to validate the generated installer as
175thoroughly as possible through extensive testing, which is mainly why this step of the release process
176is not automated through a Makefile target or similar. A good way of validating the installer is to first
177create the destroot of the port and examine it for:
178
179 * Linking: libraries and binaries should not be linked against anything that's not present by default
180   on a vanilla Mac OS X installation + developer tools, excluding even the MacPorts installation prefix;
181   this can be accomplished through the use of otool's -L flag. Currently the libraries and binaries in need
182   of linking validation are:
183             ${destroot}/opt/local/bin/daemondo
184             ${destroot}/opt/local/share/macports/Tcl/darwintrace1.0/darwintrace.dylib
185             ${destroot}/opt/local/share/macports/Tcl/macports1.0/MacPorts.dylib
186             ${destroot}/opt/local/share/macports/Tcl/pextlib1.0/Pextlib.dylib
187             ${destroot}/opt/local/share/macports/Tcl/registry2.0/registry.dylib
188 * Universal building: All the files that need linking confirmation in the step above also need to be
189   confirmed to be universal (i386/ppc on 10.5 and earlier, i386/x86_64 on 10.6 and later). A way to do this
190   is with the file(1) command:
191             file ${destroot}/opt/local/bin/daemondo:
192                  ${destroot}/opt/local/bin/daemondo: Mach-O universal binary with 2 architectures
193                  ${destroot}/opt/local/bin/daemondo (for architecture ppc):  Mach-O executable ppc
194                  ${destroot}/opt/local/bin/daemondo (for architecture i386): Mach-O executable i386
195 * tclsh shell invoked by our scripts: all scripts installed in ${destroot}/opt/local/bin (that is port,
196   portindex and portmirror) should invoke the tclsh shell through a call like:
197             #!/bin/sh
198             #\
199             exec /usr/bin/tclsh "$0" "$@"
200   thus ensuring that the default Mac OS X bundled Tcl is used in our scripts.
201 * macports1.0 Tcl package: The macports1.0 Tcl package should be sourced off its location in /opt/local/share/macports/Tcl/macports1.0
202   in every single one of our scripts in ${destroot}/opt/local/bin.
203 * Miscellaneous: anything else that might seem out of the ordinary for a fully default-configured MacPorts
204   installation.
205
206Once the above requirements have been positively asserted, the one remaining test is to make sure that the
207dmg mounts in the Finder when double-clicked, and that the pkg contained therein properly starts up Installer.app
208when it's double-clicked.
209
210
211=== Make the Release Available through Self-Update ===
212
213In order to make the release version available through selfupdate, the base/config/RELEASE_URL file in svn
214trunk needs to be updated with the tag of the release to distribute. This file is read by the cron job that
215makes the code available via rsync. See base/portmgr/mprsyncup. Though not strictly necessary, it's also good
216practice to update the same file accordingly in its branched guise.
217
218
219=== Update trunk's version for next release ===
220
221Once trunk is to be used for development of the next major version, increase its version information to
222indicate it's moved past the release version by setting the patch-level version to 99, e.g. 2.0.99 (in
223trunk/base/config/macports_version).
224
225
226=== Notify the Public of the Release ===
227
228Once the release has been posted, notification of the release should be sent/posted to the following places:
229
230 * The macports-announce@, macports-users@ and macports-dev@ mailing lists.
231 * The MacPorts website, by adapting the $macports_version_major and $macports_version_latest variables as
232   appropriate in the trunk/www/includes/common.inc file.
233 * The &macports-version; entity in trunk/doc-new/guide/xml/installing.xml.
234 * [https://trac.macports.org/news/] The MacOSforge news section (submitter: portmgr@)
235 * [http://www.versiontracker.com/dyn/moreinfo/macosx/26679 VersionTracker] (submitter: mij@)
236 * [http://sourceforge.net/projects/macports/ sourceforge] (submitted: rhwood@)
237 * [http://www.macupdate.com/info.php/id/21309/macports MacUpdate] (submitter: ???)
238 * [http://twitter.com/macports twitter] (submitter: raimue@)
239 * [https://plus.google.com/communities/110287630398071712872 Google+ Community] (submitter: raimue@)
240 * (Where else?)
241
242
243=== Use of new features in Portfiles ===
244
245Using new features introduced by a release should be delayed for 14 days. This
246should allow users to upgrade their installations to the new release. This
247delay matches the warning about outdated ports tree sources.
Note: See TracBrowser for help on using the repository browser.