Other files: stop referring to ChangeLog too
[openocd.git] / doc / manual / release.txt
1 /** @page releases Release Processes
2
3 This page provides an introduction to the OpenOCD Release Processes:
4
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.
14
15 @section releasewhy Why Produce Releases?
16
17 The OpenOCD maintainers produce <i>releases</i> periodically for many
18 reasons.  This section provides the key reasons for making releases on a
19 regular basis and why a set of <i>release processes</i> should be used
20 to produce them.
21
22 At any time, <i>source archives</i> can be produced by running
23 <code>make dist</code> in the OpenOCD project tree.  With the 0.2.0
24 release, this command will package the tree into several popular archive
25 formats: <code>openocd-\<version\>.{tar.gz,tar.bz2,zip}</code>.  If
26 produced properly, these files are suitable for release to the public.
27
28 When properly versioned and released for users, these archives present
29 several important advantages compared to using the source repository
30 (including snapshots downloaded from that repository using gitweb):
31
32 -# They allow others to package and distribute the code using
33    consistent version labels.  Users won't normally need to care
34    whose package they use, just the version of OpenOCD.
35 -# They contain a working configure script and makefiles, which
36    were produced as part of creating the archive.
37 -# Because they have been formally released by the project, users
38    don't need to try a random work-in-process revision.  Releasing
39    involves spending some time specifically on quality improvments,
40    including bugfixing source code and documentation.
41 -# They provide developers with the flexibility needed to address
42    larger issues, which sometimes involves temporary breakage.
43
44 Hopefully, this shows several good reasons to produce regular releases,
45 but the release processes were developed with some additional design
46 goals in mind.  Specifically, the releases processes should have the
47 following properties:
48
49 -# Produce successive sets of archives cleanly and consistently.
50 -# Implementable as a script that automates the critical steps.
51 -# Prevent human operators from producing broken packages, when possible.
52 -# Allow scheduling and automation of building and publishing milestones.
53
54 The current release processes are documented in the following sections.
55 They attempt to meet these design goals, but improvements may still
56 need to be made.
57
58 @subsection version_labels Version Labels
59
60 Users can display the OpenOCD version string in at least two
61 ways.  The command line <code>openocd -v</code> invocation
62 displays it; as does the Tcl <code>version</code> command.
63
64 Labels for released versions look like <em>0.3.0</em>, or
65 <em>0.3.0-rc1</em> for a preliminary release.
66 Non-released (developer) versions look like <em>0.3.0-dev</em>,
67 or <em>0.3.0-rc1-dev</em>.
68 In all cases, additional tags may be appended to those base
69 release version labels.
70
71 The <code>tools/release/version.sh</code> script is used to
72 manipulate version IDs found in the source tree.
73
74 @subsubsection releaseversions Release Versions and Tags
75
76 The OpenOCD version string is composed of three numeric components
77 separated by two decimal points: @c x.y.z, where @c x is the @a major
78 version number, @c y is the @a minor number, and @c z is the @a micro.
79 For any <em>bug-fix</em> release, the micro version number will be non-zero
80 (<code>z > 0</code>).  For a <i>minor release</i>, the micro version
81 number will be zero (<code>z = 0</code>).  For a <i>major releases</i>,
82 the minor version will @a also be zero (<code>y = 0, z = 0</code>).
83
84 After these required numeric components, release version strings
85 may contain tags such as as <em>-rc1</em> or <em>-rc2</em>.
86 These 'rc' tags indicate "release candidate" versions of the package.
87 Like the major/minor/micro numbers, these tags will be manipulated
88 by the automated release process.
89
90 The release process includes version number manipulations to the tree
91 being released, ensuring that all numbers are incremented (or rolled
92 over) at the right time and in the proper locations of the repository.
93 One of those manipulations creates a repository tag matching that
94 release's version label.
95
96 @subsubsection releaseversionsdist Packager Versions
97
98 Distributors of patched versions of OpenOCD are encouraged to extend the
99 version string with a unique version tag when producing external
100 releases, as this helps to identify your particular distribution series.
101 Knowing that a release has such patches can be essential to tracking
102 down and fixing bugs.
103
104 Packager version tags should always be suffixes to the version
105 code from the OpenOCD project, signifying modifications to the
106 original code base.  Each packager release should have a unique
107 version.
108
109 For example, the following command will add a 'foo' tag to the
110 configure.in script of a local copy of the source tree, giving
111 a version label like <em>0.3.0-foo</em>:
112
113 @code
114 tools/release/version.sh version tag add foo
115 @endcode
116
117 This command will modify the configure.in script in your working copy
118 only.  After running the @c bootstrap sequence, the tree can be patched
119 and used to produce your own derived versions.  You might check that
120 change into a private branch of your git tree, along with the other
121 patches you are providing.
122
123 You can also "bump" those tags (so "foo1" becomes "foo2" etc)
124 each time a derived package is released, incrementing the tag's
125 version to facilitate tracking the changes you have distributed.
126
127 @code
128 tools/release/version.sh version bump tag foo
129 @endcode
130
131 Of course, any patches in your branches must be provided to
132 your customers, and be in conformance with the GPL.  In most
133 cases you should also work to merge your improvements to the
134 mainline tree.
135
136 @subsubsection version_tags Development Versions and Tags
137
138 Everything except formal releases should have the tag <em>-dev</em>
139 in their version number.  This helps developers identify reports
140 created from non-release versions, and it can be detected and
141 manipulated by the release script.  Specifically, this tag will be
142 removed and re-added during the release process; it should never be
143 manipulated by developers in submitted patches.
144
145 Versions built from developer trees may have additional tags.
146 Trees built from git snapshots have <em>snapshot</em> tags.
147 When built from a "live" git tree, tags specify
148 specific git revisions:
149
150 0.3.0-rc1-dev-00015-gf37c9b8-dirty
151
152 indicates a development tree based on git revison f37c9b8
153 (a truncated version of a SHA1 hash) with some non-git
154 patches applied (the <em>dirty</em> tag).  This information
155 can be useful when tracking down bugs.
156 (Note that at this writing, the tags do not directly
157 correspond to <code>git describe</code> output.  The
158 hash ID can be used with <code>git show</code>, but
159 the preceding segments can't.)
160
161 @section releasewho Release Manager
162
163 OpenOCD archive releases will be produced by an individual filling the
164 role of <i>Release Manager</i>, hereafter abbreviated as <i>RM</i>.  This
165 individual determines the schedule and executes the release processes
166 for the community.
167
168 @subsection releasewhohow RM Authority
169
170 Each release requires one individual to fulfill the RM role; however,
171 graceful transitions of this authority may take place at any time.  The
172 current RM may transfer their authority to another contributor in a post
173 to the OpenOCD development mailing list.  Such delegation of authority
174 must be approved by the individual that will receive it and the
175 community of maintainers.  Initial arrangements with the new RM should
176 be made off-list, as not every contributor wants these responsibilities.
177
178 @subsection releasewhowhat RM Responsibilities
179
180 In addition to the actual process of producing the releases, the RM is
181 responsible for keeping the community informed of all progress through
182 the release cycle(s) being managed.  The RM is responsible for managing
183 the changes to the package version, though the release tools should
184 manage the tasks of adding or removing any required development branch
185 tags and incrementing the version.
186
187 These responsibilities matter most towards the end of the release
188 cycle, when the RM creates the first RC and all contributors enter
189 a quality-improvement mode.  The RM works with other contributors
190 to make sure everyone knows what kinds of fixes should merge, the
191 status of major issues, and the release timetable.
192
193 In particular, the RM has the final decision on whether a given
194 bug should block the release.
195
196 @section releasewhen Release Schedule
197
198 The OpenOCD release process must be carried out on a periodic basis, so
199 the project can realize the benefits presented in answer to the question,
200 @ref releasewhy.
201
202 Starting with the 0.2.0 release, the OpenOCD project expects to produce
203 new releases every few months.
204 Bug fix releases could be provided more frequently.  These release
205 schedule goals may be adjusted in the future, after the project
206 maintainers and distributors receive feedback and experience.
207
208 More importantly, the statements made in this section do not create an
209 obligation by any member of the OpenOCD community to produce new
210 releases on regular schedule, now or in the future.
211
212 @subsection releasewhenexample Sample Schedule
213
214 The RM must pro-actively communicate with the community from the
215 beginning of the development cycle through the delivery of the new
216 release.  This section presents guidelines for scheduling key points
217 where the community must be informed of changing conditions.
218
219 If Tn is the time of release n, then the following schedule
220 might describe some key T0-to-T1 release cycle milestones.
221
222 - T0 ... End of T0 release cycle. T1 cycle starts, with merge
223   window opening.  Developers begin to merge queued work.
224 - <em>... several weeks of merge window ...</em>
225 - RC1 ... Close mainline to new work.  Produce RC1
226   release, begin testing phase; developers are in "bugfix mode",
227   all other work is queued; send out planned endgame schedule.
228 - RC2 ... Produce RC2 and send schedule update to
229   mailing list, listing priorities for remaining fixes
230 - <em>... more RC milestones, until ready ...</em>
231 - T1: End of T1 release cycle. T2 cycle starts, with merge
232   window opening.  Developers begin to merge queued work.
233
234 Note that until it happens, any date for T1 is just a goal.
235 Critical bugs prevent releases from happening.  We are just
236 beginning to use this window-plus-RCs process, so the lengths
237 of the merge windows versus the RC phase is subject to change.
238 Most projects have RC phases of a month or more.
239
240 Some additional supplemental communication will be desirable.  The above
241 list omits the step-by-step instructions to daily release management.
242 Individuals performing release management need to have the ability to
243 interact proactively with the community as a whole, anticipating when
244 such interaction will be required and giving ample notification.
245
246 The next section explains why the OpenOCD project allows significant
247 flexibility in the part of the development that precedes the release
248 process.
249
250 @subsection releasewhenflex Schedule Flexibility
251
252 The Release Manager should attempt to follow the guidelines in this
253 document, but the process of scheduling each release milestone should be
254 community driven at the start.  Features that don't complete before
255 the merge window closes can be held (perhaps in some branch) until
256 the next merge window opens, rather than delaying the release cycle.
257
258 The Release
259 Manager cannot schedule the work that will be done on the project,
260 when it will be submitted, reviewed, and deemed suitable to be committed.
261 That is, the RM cannot act as a priest in a cathedral; OpenOCD uses
262 the bazaar development model.  The release schedule must adapt
263 continuously in response to changes in the rate of work.
264 Fewer releases may be
265 required if developers contribute less patches, and more releases may be
266 desirable if the project continues to grow and experience high rates of
267 community contribution.  During each cycle, the RM should be tracking
268 the situation and gathering feedback from the community.
269
270 @section releasehow Release Process: Step-by-Step
271
272 The release process is not final; it may need more iterations
273 to work out bugs.
274 While there are release scripts, key steps require community
275 support; the Release Manager isn't the only participant.
276
277 The following steps should be followed to produce each release:
278
279 -# Produce final patches to mainline (or a release branch).  Nobody
280    except the RM should be committing anything.
281   -# Finalize @c NEWS file to describe the changes in the release
282     - This file is used to automatically post "blurbs" about the project.
283     - This material should be produced during the development cycle.
284     - Add a new item for each @c NEWS-worthy contribution, when committed.
285   -# Bump library version if our API changed (not yet required)
286   -# Update and commit the final package version in @c configure.in:
287      <code>tools/release/version.sh</code> may help ensure the versions
288      are named consistently:
289     -# Remove @c -dev tag.
290     -# Update the @c -rc tag:
291       - If producing the final release from an -rc series, remove it
292       - If producing the first RC in a series, add rc1
293       - If producing the next RC in a series, bump the rc number
294     -# Commit that version change.
295   -# Create a git tag for the final commit, with a tag name matching
296      the version string in <code>configure.in</code>:
297 @verbatim
298 PACKAGE_VERSION="x.y.z"
299 PACKAGE_TAG="v${PACKAGE_VERSION}"
300 git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}"
301 @endverbatim
302 -# Prepare to resume normal development on mainline:
303   - Restore @c -dev version tag.
304   - To start a new major (or minor) release cycle on the @c master branch:
305     - Archive @c NEWS file as "<code>doc/news/NEWS-${PACKAGE_VERSION}</code>".
306     - Create a new @c NEWS file for the next release
307   - Commit those changes, and push the commit and the release tag
308     to mainline.
309 -# Produce the package source archives:
310   -# <em>Start with a new clone of the source tree</em>, with the
311      release's tag.  This is used only for producing these packages.
312   -# Checkout the appropriate tag:
313 <code>git checkout "${PACKAGE_VERSION}"</code>
314   -# @c bootstrap, @c configure, and @c make the package.
315   -# Run <code>make distcheck</code> to produce the distribution archives.
316   -# Run <code>make maintainer-clean</code> verify the repository is empty.
317   -# Create signature files using @c md5sum, @c sha1sum, etc.
318 -# Publish documentation for the release:
319   - Allow users to access the documentation for each of our releases.
320   - Place static copies of the following files on the project website:
321     - @c NEWS: to provide a blurb for each release
322     - User's Guide, Developer Manual: to allow easy on-line viewing
323 -# Upload packages and post announcements of their availability:
324   -# Release packages into files section of project sites:
325     - SF.net:
326      -# Create a new folder named "${PACKAGE_VERSION}"
327      -# Select new folder as the target for uploads.
328      -# Upload files via Web interface into new
329      -# Set platform types for each archive:
330        - .tar.bz2: Linux, Mac
331        - .tar.gz: BSD, Solaris, Others
332        - .zip: Windows
333     - Berlios:
334      -# Create the new release for the new version.
335      -# Provide @c NEWS file, as requested.
336      -# Upload files via FTP to ftp://ftp.berlios.de/incoming/
337      -# Edit descriptions for each file.
338      -# Click button to send E-mail Release Notice.
339   -# Post announcement e-mail to the openocd-development list.
340   -# Announce updates on freshmeat.net and other trackers.
341   -# Submit big updates to news feeds (e.g. Digg, Reddit, etc.).
342
343 To start a bug-fix release branch:
344 -# Create a new branch, starting from a major or
345    minor release tag
346 -# Restore @c -dev version tag.
347 -# Bump micro version number in configure.in
348 -# Backport bugfix patches from mainline into that branch.
349    (Always be sure mainline has the fix first, so it's hard
350    to just lose a bugfix.)
351 -# Commit and push those patches.
352 -# When desired, release as above ... except note that the next
353    release of a bugfix branch is never a new major or minor release
354
355 @subsection releasescriptcmds Release Script Commands
356
357 The @c release.sh script automates some of the steps involved
358 in making releases, simplifying the Release Manager's work.
359
360 The release script can be used for two tasks:
361 - Creating releases and starting a new release cycle:
362 @code
363 git checkout master
364 tools/release.sh --type=minor --final --start-rc release
365 @endcode
366 - Creating a development branch from a tagged release:
367 @code
368 git checkout 'v0.2.0'
369 tools/release.sh --type=micro branch
370 @endcode
371
372 Both of these variations make automatic commits and tags in your
373 repository, so you should be sure to run it on a cloned copy before
374 proceding with a live release.
375
376 @subsection releasescriptopts Release Script Options
377
378 The @c release.sh script recognizes some command-line options that
379 affect its behavior:
380
381 - The @c --start-rc indicates that the new development release cycle
382   should start with @c -rc0.  Without this, the @c -rc tag will be omitted,
383   leading to non-monotonic versioning of the in-tree version numbers.
384 - The @c --final indicates that the release should drop the @c -rc tag,
385   to going from @c x.y.z-rcN-dev to x.y.z.
386
387 @subsection releasescriptenv Release Script Environment
388
389 The @c release.sh script recognizes some environment variables which
390 affect its behavior:
391
392 - @c CONFIG_OPTS : Passed as options to the configure script.
393 - @c MAKE_OPTS : Passed as options to the 'make' processes.
394
395 @section releasetutorial Release Tutorials
396
397 This section should contain a brief tutorial for using the Release 
398 Script to perform release tasks, but the new script needs to be
399 used for 0.3.0.
400
401 @section releasetodo Release Script Shortcomings
402
403 Improved automated packaging and distribution of OpenOCD requires more
404 patching of the configure script.  The final release script should be
405 able to manage most steps of the processes.  The steps requiring user
406 input could be guided by an "assistant" that walks the Release Manager
407 through the process from beginning to end, performing basic sanity
408 checks on their various inputs (e.g. the @c NEWS blurb).
409
410  */
411 /** @file
412 This file contains the @ref releases page.
413  */