1 /** @page releases Release Processes
3 This page provides an introduction to the OpenOCD Release Processes:
5 - @ref releasewhy - Explain the motivations for producing
6 releases on a regular basis.
7 - @ref releasewho - Describes the responsibilities and
8 authority required to produce official OpenOCD releases.
9 - @ref releasewhen - Provides guidelines for scheduling
10 activities for each release cycle.
11 - @ref releasehow - Outlines all of the steps for the
12 processes used to produce and release the package source archives.
13 - @ref releasescript - Introduces the automated @c release.sh script.
15 @section releasewhy Why Produce Releases?
17 The OpenOCD maintainers should produce <i>releases</i> periodically. This
18 section gives several reasons to explain the reasons for making releases
19 on a regular basis. These reasons lead to motivation for developing and
20 following a set of <i>release processes</i>. The actual processes are
21 described in the remainder of the @ref releases sections.
23 At any time, a "source archives" can be produced by running 'make dist'
24 in the OpenOCD project tree. With the 0.2.0 release, this command will
25 produce openocd-\<version\>.{tar.gz,tar.bz2,zip} archives. These files
26 will be suitable for being released when produced properly.
28 When released for users, these archives present several important
29 advantages when contrasted to using the Subversion repository:
31 -# They allow others to package and distribute the code to users.
32 -# They build easier for developers, because they contain
33 a working configure script that was produced by the Release Manager.
34 -# They prevent users from trying a random HEAD revision of the trunk.
35 -# They free developers from answering questions about trunk breakage.
37 Hopefully, this shows several good reasons to produce regular releases,
38 but these release processes were developed with some additional design
39 goals in mind. Specifically, the releases processes should have the
42 -# Produce successive sets of release archives cleanly and consistently.
43 -# Implementable as a script that automates the critical release steps.
44 -# Prevent human operators from producing bad releases, when possible.
45 -# Allow scheduling and automation of release process milestones.
47 The current release processes are documented in the following sections.
48 They attempt to meet these design goals, but there may improvements
49 remaining to be made toward automating the process.
51 @section releaseversions Release Versions
53 The OpenOCD version string is composed of three numeric components
54 separated by two decimal points: @c x.y.z, where @c x is the @a major
55 version number, @c y is the @a minor number, and @c z is the @a micro.
57 For a <i>bug-fix</i> release, the micro version number will be non-zero
58 (<code>z > 0</code>). For a <i>minor release</i>, the micro version
59 number will be zero (<code>z = 0</code>). For a <i>major releases</i>,
60 the minor version will @a also be zero (<code>y = 0, z = 0</code>).
62 The trunk and all branches should have the tag '-in-development' in
63 their version number. This tag helps developers identify reports
64 created from the Subversion repository, and it can be detected and
65 manipulated by the release script. Specifically, this tag will be
66 removed and re-added during the release process; it should never be
67 manipulated by developers in submitted patches.
69 @subsection releaseversionsdist Patched Versions
71 Distributors of patched versions of OpenOCD are encouraged to extend
72 the version string when producing external releases, as this helps to
73 identify your particular distribution series.
75 @subsection releaseversionsdist Version Processes
77 The release process includes version number manipulations to the tree
78 being released, ensuring that all numbers are incremented at the right
79 time and in the proper locations of the repository.
81 The version numbers for any branch should monotonically
82 increase to the next successive integer, except when reset to zero
83 during major or minor releases. The community should decide when
84 major and minor milestones will be released.
86 @section releasewho Release Manager
88 OpenOCD archive releases will be produced by an individual filling the
89 role of <i>Release Manager</i>, hereafter abbreviated as <i>RM</i>. This
90 individual determines the schedule and executes the release processes
93 @subsection releasewhohow RM Authority
95 Each release requires one individual to fulfill the RM role; however,
96 graceful transitions of this authority may take place at any time. The
97 current RM may transfer their authority to another contributor in a post
98 to the OpenOCD development mailing list. Such delegation of authority
99 must be approved by the individual that will receive it and the
100 community of maintainers. Initial arrangements with the new RM should
101 be made off-list, as not every contributor wants these responsibilities.
103 @subsection releasewhowhat RM Responsibilities
105 In addition to the actual process of producing the releases, the RM is
106 responsible for keeping the community informed of all progress through
107 the release cycle(s) being managed. The RM is responsible for managing
108 the changes to the package version, though the release tools should
109 manage the tasks of adding or removing any required development branch
110 tags and incrementing the version.
112 @section releasewhen Release Schedule
114 The OpenOCD release process must be carried out on a periodic basis, so
115 the project can realize the benefits presented in answer to the question,
118 Starting with the 0.2.0 release, the OpenOCD project should produce a
119 new minor release every month or two, with a major release once a year.
120 Bug fix releases could be provided more frequently. These release
121 schedule goals may be adjusted in the future, after the project
122 maintainers and distributors receive feedback and experience.
124 More importantly, the statements made in this section do not create an
125 obligation by any member of the OpenOCD community to produce new
126 releases on regular schedule, now or in the future.
128 @subsection releasewhenexample Sample Schedule
130 The RM must pro-actively communicate with the community from the
131 beginning of the development cycle through the delivery of the new
132 release. This section presents guidelines for scheduling key points
133 where the community must be informed of changing conditions.
135 If T is the time of the next release, then the following schedule
136 might describe some of the key milestones of the new release cycle:
138 - T minus one month: start of new development cycle
139 - T minus two weeks: announce pending trunk closure to new work
140 - T minus one week: close trunk to new work, begin testing phase
141 - T minus two days: call for final bug fixes
142 - T minus one day: produce -rc packages and distribute to testers
143 - T minus one hour: produce final packages and post on-line
144 - T minus zero: Announce the release to our mailing list and the world.
146 Some additional supplemental communication will be desirable. The above
147 list omits the step-by-step instructions to daily release management.
148 Individuals performing release management need to have the ability to
149 interact proactively with the community as a whole, anticipating when
150 such interaction will be required and giving ample notification.
152 The next section explains why the OpenOCD project allows significant
153 flexibility in the part of the development that precedes the release
156 @note The OpenOCD project does not presently produce -rc packages. As
157 such, the step suggested in the list above should be read as trying to
158 stimulate others to test the project build and packaging on as many
159 platforms as possible. This proposition will be palatable once release
160 management tools have been committed to the tree.
162 @subsection releasewhenflex Schedule Flexibility
164 The Release Manager should attempt to follow the guidelines in this
165 document, but the process of scheduling each release milestone should be
166 community driven at the start. By the end, missing features that were
167 scheduled for a release must be dropped by the Release Manager, rather
168 than allowing the release cycle to be delayed while waiting for them.
170 Despite any assurances this schedule may appear to give, the Release
171 Manager cannot schedule the work that will be done on the project,
172 when it will be submitted, review, and deemed suitable to be committed.
173 In this way, the RM cannot act as a priest in a cathedral; OpenOCD uses
174 the bazaar development model. The release schedule must adapt
175 continuously in response to changes in the rate of churn.
177 In particular, the suggested period of "one or two month" reflects some
178 expectation of a fairly high rate of development. Fewer releases may be
179 required if developers contribute less patches, and more releases may be
180 desirable if the project continues to grow and experience high rates of
181 community contribution. During each cycle, the RM should be tracking
182 the situation and gathering feedback from the community .
184 @section releasehow Release Process: Step-by-Step
186 The release process may require a few iterations to work out any bugs.
187 Even with the release script, some steps require clear user intervention
188 -- and not only by the Release Manager.
190 The following steps should be followed to produce each release:
192 -# Produce final patches to the trunk (or release branch):
193 -# add NEWS item to describe the release changes? (not ready for 0.2.0)
194 - the community should try to help produce this material
195 - can be used to automatically post "blurbs" about the project.
196 -# bump library version if our API changed (not yet required)
197 -# Remove -in-development tag from package version:
198 - For major/minor releases, remove version tag from trunk.
199 - For bug-fix releases, remove version tag from release branch.
200 -# Produce and verify the binary packages:
201 -# Start with a clean working copy, used for producing releases only.
202 -# produce a ChangeLog for the release (using svn2cl).
203 -# bootstrap, configure, and build the package.
204 -# run 'make distcheck' to produce the distribution archives.
205 -# run 'make maintainer-clean'; verify the repository is empty again.
206 -# Branch or tag the required tree in the Subversion repository:
207 - Tags and branches for releases must be named consistently: @par
208 "${PACKAGE_TARNAME}-${PACKAGE_VERSION}"
209 - For a major/minor release from the main trunk, the code should be
210 branched and tagged in the repository:
212 svn cp .../trunk .../branches/${RELEASE_BRANCH}
213 svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
215 - For bug-fix releases produced in their respective branch, a tag
216 should be created in the repository:
218 svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
220 -# Prepare to resume normal development activities:
221 - For major/minor release from the trunk:
222 -# Bump major or minor package version in trunk.
223 -# Restore version tag to trunk and release branch.
224 - For bug-fix releases from a release branch:
225 -# Bump bug-fix version in release branch.
226 -# Restore version tag to release branch.
227 -# Publish documentation for the release:
228 - Allow users to access the documentation for each of our releases.
229 - Place static copies of the following files on the project website:
230 - NEWS: to provide a blurb for each release (not yet used)
231 - ChangeLog: to show exactly what has been changed
232 - User Guide, Developer Manual: to allow easy on-line viewing
233 -# Upload packages and post announcements of their availability:
234 -# Release packages into files section of berliOS project site.
235 -# Post announcement e-mail to the openocd-development list.
236 -# Announce updates on freshmeat.net and other trackers.
237 -# Submit big NEWS updates to news feeds (e.g. Digg, Reddit, etc.).
239 @section releasescript The Release Script
241 Many of the processes described in the last section are no longer
242 entrusted to humans. Instead, the @c release.sh script provides
243 automation of the mechanical steps.
245 Presently, the @c release.sh script automates steps 1(c) through 4,
246 allowing the Release Manager from perform these tasks in easy steps.
248 The following task still need to be automated:
250 - Step 5: produce documentation for website using released source archive.
251 - Step 6(a): package archive upload process.
252 - Step 6(b): package announcement e-mail process.
253 - Step 6(c): post files and announce them using releaseforge.
255 In addition, support for '-rc' releases needs to be added.
257 @subsection releasescriptcmds Release Script Commands
259 The following output was taken from the release script:
261 usage: tools/release.sh <command>
264 info Show a summary of the next pending release.
265 release Release the current tree as an archive.
266 upload Upload archives to berliOS project site
269 bootstrap Prepare the working copy for configuration and building.
270 configure Configures the package; runs bootstrap, if needed.
271 build Compiles the project; runs configure, if needed.
274 changelog Generate a new ChangeLog using svn2cl.
275 package Produce new distributable source archives.
276 stage Move archives to staging area for upload.
279 commit Perform branch and tag, as appropriate for the version.
280 branch Create a release branch from the project trunk.
281 tag Create a tag for the current release branch.
284 version ... Perform version number and tag manipulations.
285 clean Forces regeneration of results.
286 clean_all Removes all traces of the release process.
287 help Provides this list of commands.
289 For more information about this script, see the Release Processes page
290 in the OpenOCD Developer's Manual (doc/manual/release.txt).
292 WARNING: This script should be used by the Release Manager ONLY.
295 Run <code>tools/release.sh help</code> for current command support.
297 @subsection releasescriptenv Release Script Environment
299 The @c release.sh script recognizes some environment variables which
302 - @c CONFIG_OPTS : Passed as options to the configure script.
303 - @c MAKE_OPTS : Passed as options to the 'make' processes.
304 - @c RELEASE_DRY_RUN : Set this to null to perform the live release.
305 Unless this variable has been (un)set, the release commands will not
306 affect the repository.
308 Proper option handling should be added to set these variables in script.
310 @section releasetutorial Release Tutorials
312 This section provides tutorials for using the Release Script to perform
313 common release tasks.
315 @subsection releasetutorialminor Minor Release Tutorial
317 The tutorials in this section assume the following environment
318 variables have been set properly:
320 SVN_USER="maintainer"
321 SVN_URL="https://${SVN_USER}@svn.berlios.de/svnroot/repos/openocd"
324 @subsection releasetutorialminor Minor Release Tutorial
326 This section provides a step-by-step tutorial for a Release Manager to
327 use to run the @c release.sh script to produce a minor release.
329 If the proper environment has been set, the following steps will produce
332 -# Check out (or update) the project trunk from the berliOS repository:
334 svn checkout "${SVN_URL}/trunk" openocd-trunk
336 -# Change to the new working copy directory:
340 -# Run @c release.sh to produce the minor release:
345 @subsection releasetutorialmicro Bug-Fix Release Tutorial
347 This section provides a step-by-step tutorial for a Release Manager to
348 use to run the @c release.sh script to produce a bug-fix release.
350 In addition to the environment variables described in the introduction
351 to these tutorials, the following variables are also used in the
352 instructions for this section:
354 PACKAGE_BRANCH_VERSION="x.y.z"
355 PACKAGE_BRANCH="openocd-${PACKAGE_BRANCH_VERSION}"
358 If the proper environment has been set, the following steps will produce
359 a new bug-fix release:
361 -# Check out (or update) the release branch from the project repository:
363 svn checkout "${SVN_URL}/branches/${PACKAGE_BRANCH}" "${PACKAGE_BRANCH}"
366 cd "${PACKAGE_BRANCH}"
368 -# Run @c release.sh to produce the bug-fix release:
373 @section releasetodo Release Script Shortcomings
375 Improved automated packaging and distribution of OpenOCD requires more
376 patching of the configure script. The final release script should be
377 able to manage most steps of the processes. The steps requiring user
378 input could be guided by an "assistant" that walks the Release Manager
379 through the process from beginning to end, performing basic sanity
380 checks on their various inputs (e.g. the NEWS blurb).
384 This file contains the @ref releases page.