source: trunk/base/portmgr/ReleaseProcess @ 32893

Last change on this file since 32893 was 32893, checked in by jmpp@…, 13 years ago

Use new variable names controling our website.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 12.1 KB
Line 
1
2= MacPorts Release Process =
3
4This file documents the evolving MacPorts release process.
5$Id: ReleaseProcess 32893 2008-01-14 15:34:44Z jmpp@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.5.x, 1.6.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_1_6) 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" http://svn.macports.org/repository/macports/branches/release_1_6
43 svn cp [-r<rev>] -m "commit-message" http://svn.macports.org/repository/macports/trunk/base \
44     http://svn.macports.org/repository/macports/branches/release_1_6
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 svnmerge.py tool (provided by the subversion port) to
53maintain merge tracking information between release branches and trunk/base if you intend to
54merge revisions back and forth between them, which is a very likely scenario. To do this, you
55must initialize the tracking information from within the "base" directory of your checkout of
56the branch you intend to manage:
57
58 svn co http://svn.macports.org/repository/macports/branches/release_1_6 branches/release_1_6
59 cd branches/release_1_6/base
60 svnmerge.py init
61 svn ci -F svnmerge-commit-message.txt
62
63
64=== Prepare the code for Release ===
65
66In preparation for a release, several things should be completed within the code:
67
68 * Update the file base/ChangeLog in both trunk and the release branch to reflect the appropriate changes.
69 * Update the file base/config/mp_version with the target release number. Note that this is a floating
70   point number that corresponds to the release number; it should correspond roughly to the release number
71   where possible. Release 1.6.1, for instance, would be represented by the floating point number 1.610.
72   The version number in mp_version is displayed by the port command as the version of MacPorts,
73   and is used by the selfupdate command to determine whether a newer version of code is available.
74   This number should be different between trunk and a release branch, the former greater to differentiate
75   it from the latter.
76 * Update the autoconf 'configure' script through the provided base/regen.sh script once the version number
77   in mp_version has been changed, since the former reads the latter.
78 * Make sure that these and any other changes or bug fixes are made on and/or merged between the release branch
79   and trunk as needed. For instance, if you've made changes to ChangeLog only on the release branch,
80   those changes should be merged back into trunk as well.
81
82
83=== Tag the Release ===
84
85Once the release is ready, it must be tagged so that the release components may be fetched in the future,
86to ensure replicability. Generally, a release candidate is first tagged and built. When and if it is
87approved as the actual release, an additional tag is created that names the same sources.
88
89Tagging conventions:
90
91 * release_1_6_0-rc1 (release candidate 1 for release 1.6.0)
92 * release_1_6_0 (tagged release 1.6.0)
93 * release_1_6_0-archive (tagged release 1.6.0 -- complete archive)
94 * release_1_6_1 (1.6.1 release)
95
96We first tag the branched base directory to make up the final release:
97
98 svn cp -m "commit-message" http://svn.macports.org/repository/macports/branches/release_1_6 \
99     http://svn.macports.org/repository/macports/tags/release_1_6_0
100
101Although only the base subdirectory is branched and tagged for a given major release, we also create a
102separate tag for the entire tree (base sources and full ports tree) at the time the final release tag is
103created (only for major releases, 1.x.0), in order to provide a stake in the ground that specifies a set
104of ports intended to work with that release. Note that this tag incorporates the entire svn trunk directory
105at the revision number at which the final release was tagged.
106
107The necessary working copy to create such a tag is created by checking out all of trunk at the specific
108revision of the final tagging of base and then switching the base directory to the appropriate release
109tag URL. For instance:
110
111 svn co [-r<rev>] http://svn.macports.org/repository/macports/trunk release_1.6.0-archive
112 cd release_1.6.0-archive/base
113 svn switch http://svn.macports.org/repository/macports/tags/release_1_6_0/base
114
115And finally we tag the entire directory as release_1_6_0-archive:
116
117 cd ../../
118 svn cp -m "commit-message" release_1.6.0-archive http://svn.macports.org/repository/macports/tags/release_1_6_0-archive
119
120
121=== Create & Post Release Tarballs ===
122
123The release tarballs are tar.bz2 and tar.gz archives of the base directory only and of the entire svn tree
124for a particular release. They are named with the following naming convention:
125
126 MacPorts-1.6.0.tar.{bz2,gz} (base directory only, corresponding to tag release_1_6_0)
127 MacPorts-1.6.0-archive.tar.{bz2,gz} (complete archives corresponding to tag release_1_6_0-archive)
128
129The following commands issued to the top level Makefile will generate all the tarballs and checksums:
130
131 make ARC=yes DISTVER=1.6.0 distfromsvn
132
133Note that if you omit the "ARC=yes" flag at the start of the make call then the full archive tarballs will not be produced.
134
135All these tarballs are uploaded via svn to the http://svn.macports.org/repository/macports/downloads/MacPorts-1.6.0/
136directory.
137
138Additionally, a file is created, and posted to the same location, that contains md5, sha1, and rmd160 checksums
139for each of the files:
140
141 MacPorts-1.6.0.chk.txt
142 (We should have a way to sign these checksums, and have the signer's keys posted somewhere.
143 Security experts in the project, would you be interested in leading this effort? Eric? Mark? Anyone else?)
144
145
146=== Create Release Disk Image(s) ===
147
148The dmg is a Mac OS X disk image that contains a standalone installer, configured in the usual way, for major
149MacPorts releases (1.x.0), named in a consistent fashion and incorporating the OS version for which it
150was built.
151
152 MacPorts-1.6.0-10.4-Tiger.dmg
153 MacPorts-1.6.0-10.5-Leopard.dmg
154
155To create a disk image, use the MacPorts port. The Portfile will need to be updated to incorporate the
156proper release version and checksums, and the release tarballs will need to be already uploaded to the
157downloads section of the site (wherefrom the sources are fetched by the MacPorts port to build the dmg
158for the release). Make sure the ports tree you're using to build the dmg's is fully up to date, as to
159insure the resource files in the files/ directory of the port are current (fetched through svn:externals
160off the base/portmgr/dmg directory of the current final release tag).
161
162 sudo port -d dmg MacPorts
163
164Name the dmg appropriately, and generate checksums, which will need to be added to the existing checksums
165file in the downloads directory:
166
167 cd work
168 mv MacPorts-1.6.0.dmg MacPorts-1.6.0-10.5-Leopard.dmg
169 for dmg in MacPorts-1.6.0-*.dmg; do for type in -md5 -sha1 -ripemd160; do openssl dgst $type $dmg; done >> MacPorts-1.6.0.chk.txt; done
170
171These new products, along with the new checksums, also have to be posted to the appropriate downloads
172directory of the MacPorts svn repository. Developers are required to validate the generated installer as
173thoroughly as possible through extensive testing, which is mainly why this step of the release process
174is not automated through a Makefile target or similar. A good way of validating the installer is to first
175create the destroot of the port and examine it for:
176
177 * Linking: libraries and binaries should not be linked against anything that's not present by default
178   on a vanilla Mac OS X installation + developer tools, excluding even the MacPorts installation prefix;
179   this can be accomplished through the use of otool's -L flag. Currently the libraries and binaries in need
180   of linking validation are:
181             ${destroot}/Library/Tcl/macports1.0/MacPorts.dylib
182             ${destroot}/opt/local/bin/daemondo (only built on 10.4 and later)
183             ${destroot}/opt/local/share/macports/Tcl/darwintrace1.0/darwintrace.dylib
184             ${destroot}/opt/local/share/macports/Tcl/pextlib1.0/Pextlib.dylib
185             ${destroot}/opt/local/share/macports/Tcl/registry2.0/registry.dylib
186             ${destroot}/opt/local/share/macports/Tcl/tclobjc1.0/tclobjc.dylib
187 * Universal building: When building for Tiger and above, all the files that need linking confirmation in the
188   step above also need to be confirmed of the universal type. A way to do this is through the file(1) command:
189             file ${destroot}/opt/local/bin/daemondo:
190                  ${destroot}/opt/local/bin/daemondo: Mach-O universal binary with 2 architectures
191                  ${destroot}/opt/local/bin/daemondo (for architecture ppc):  Mach-O executable ppc
192                  ${destroot}/opt/local/bin/daemondo (for architecture i386): Mach-O executable i386
193 * tclsh shell invoked by our scripts: all scripts installed in ${destroot}/opt/local/bin (that is port,
194   portindex and portmirror) should invoke the tclsh shell through a call like:
195             #!/bin/sh
196             #\
197             exec /usr/bin/tclsh "$0" "$@"
198   thus ensuring that the default Mac OS X bundled Tcl is used in our scripts.
199 * macports1.0 Tcl package: The macports1.0 Tcl package should be sourced off its default location in /Library/Tcl/macports1.0
200   in every single one of our scripts in ${destroot}/opt/local/bin.
201 * Miscellaneous: anything else that might seem out of the ordinary for a fully default-configured MacPorts
202   installation.
203
204Once the above requirements have been positively asserted, the one remaining test is to make sure that the
205dmg mounts in the Finder when double-clicked, and that the pkg contained therein properly starts up Installer.app
206when it's double-clicked.
207
208
209=== Make the Release Available through Self-Update ===
210
211In order to make the release version available through selfupdate, the base/config/RELEASE_URL file in svn
212trunk needs to be updated with the tag of the release to distribute. This file is read by the cron job that
213makes the code available via rsync. See base/portmgr/mprsyncup. Though not strictly necessary, it's also good
214practice to update the same file accordingly in its branched guise.
215
216
217=== Notify the Public of the Release ===
218
219Once the release has been posted, notification of the release should be sent/posted to the following places:
220
221 * The macports-announce@, macports-users@ and macports-dev@ mailing lists.
222 * The MacPorts website, by adapting the $macports_version_major and $macports_version_latest variables as appropriate in the trunk/www/includes/common.inc file.
223 * [http://www.apple.com/downloads/macosx/unix_open_source/macports.html Apple's downloads page] (submitter: jmpp@)
224 * [http://freshmeat.net/projects/macports/ Freshmeat] (submitter: mww@)
225 * [http://www.versiontracker.com/dyn/moreinfo/macosx/26679 VersionTracker] (submitter: mij@)
226 * [http://sourceforge.net/projects/macports/ sourceforge] (submitted: rhwood@)
227 * [http://www.macupdate.com/info.php/id/21309/macports MacUpdate] (submitter: ???)
228 * (Where else?)
Note: See TracBrowser for help on using the repository browser.