release.txt 18.1 KB
Newer Older
1
2
/** @page releases Release Processes

3
This page provides an introduction to the OpenOCD Release Processes:
4

5
6
7
8
9
10
11
12
13
- @ref releasewhy - Explain the motivations for producing
  releases on a regular basis.
- @ref releasewho - Describes the responsibilities and
  authority required to produce official OpenOCD releases.
- @ref releasewhen - Provides guidelines for scheduling
  activities for each release cycle.
- @ref releasehow - Outlines all of the steps for the
  processes used to produce and release the package source archives.
- @ref releasescript - Introduces the automated @c release.sh script.
14

15
16
@section releasewhy Why Produce Releases?

zwelch's avatar
zwelch committed
17
18
19
20
The OpenOCD maintainers produce <i>releases</i> periodically for many
reasons.  This section provides the key reasons for making releases on a
regular basis and why a set of <i>release processes</i> should be used
to produce them.
21

zwelch's avatar
zwelch committed
22
23
24
25
26
At any time, <i>source archives</i> can be produced by running
<code>make dist</code> in the OpenOCD project tree.  With the 0.2.0
release, this command will package the tree into several popular archive
formats: <code>openocd-\<version\>.{tar.gz,tar.bz2,zip}</code>.  If
produced properly, these files are suitable for release to the public.
27
28

When released for users, these archives present several important
29
advantages when contrasted to using the git repository:
30

zwelch's avatar
zwelch committed
31
-# They allow others to package and distribute the code.
32
33
-# They build easier for developers, because they contain
   a working configure script that was produced by the Release Manager.
34
35
-# They prevent users from trying a random work-in-process revision.
-# They free developers from answering questions about mainline breakage.
36
37

Hopefully, this shows several good reasons to produce regular releases,
zwelch's avatar
zwelch committed
38
but the release processes were developed with some additional design
39
40
41
goals in mind.  Specifically, the releases processes should have the
following properties:

zwelch's avatar
zwelch committed
42
43
44
45
-# Produce successive sets of archives cleanly and consistently.
-# Implementable as a script that automates the critical steps.
-# Prevent human operators from producing broken packages, when possible.
-# Allow scheduling and automation of building and publishing milestones.
46
47

The current release processes are documented in the following sections.
48
They attempt to meet these design goals, but there may improvements
49
50
remaining to be made toward automating the process.

51
52
53
54
55
56
57
58
59
60
61
@section releaseversions Release Versions

The OpenOCD version string is composed of three numeric components
separated by two decimal points: @c x.y.z, where @c x is the @a major
version number, @c y is the @a minor number, and @c z is the @a micro.

For a <i>bug-fix</i> release, the micro version number will be non-zero
(<code>z > 0</code>).  For a <i>minor release</i>, the micro version
number will be zero (<code>z = 0</code>).  For a <i>major releases</i>,
the minor version will @a also be zero (<code>y = 0, z = 0</code>).

zwelch's avatar
zwelch committed
62
63
64
@subsection releaseversiontags Version Tags

After these required numeric components, the version string may contain
65
one or more <i>version tags</i>, such as '-rc1' or '-dev'.
zwelch's avatar
zwelch committed
66

67
Mainline and all branches should have the tag '-dev' in
68
their version number.  This tag helps developers identify reports
69
created from the git repository, and it can be detected and
70
71
72
73
manipulated by the release script.  Specifically, this tag will be
removed and re-added during the release process; it should never be
manipulated by developers in submitted patches.

zwelch's avatar
zwelch committed
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
The 'rc' tags indicate a "release candidate" version of the package.
This tag will also be manipulated by the automated release process.

Additional tags may be used as necessary.

@subsection releaseversionsdist Packager Versions

Distributors of patched versions of OpenOCD are encouraged to extend the
version string with a unique version tag when producing external
releases, as this helps to identify your particular distribution series.

For example, the following command will add a 'foo1' tag to the
configure.in script of a local copy of the source tree:

@code
tools/release.sh version bump tag foo
@endcode
91

zwelch's avatar
zwelch committed
92
93
94
95
96
This command will modify the configure.in script in your working copy
only.  After running the @c bootstrap sequence, the tree can be patched
and used to produce your own derived versions.  The same command can be
used each time the derived package is released, incrementing the tag's
version to facilitate tracking the changes you have distributed.
97

zwelch's avatar
zwelch committed
98
@subsection releaseversionhow Version Processes
99
100
101
102
103

The release process includes version number manipulations to the tree
being released, ensuring that all numbers are incremented at the right
time and in the proper locations of the repository.

zwelch's avatar
zwelch committed
104
105
The version numbers for any branch should increase monotonically
to the next successive integer, except when reset to zero
106
107
108
109
during major or minor releases.  The community should decide when
major and minor milestones will be released.

@section releasewho Release Manager
110
111

OpenOCD archive releases will be produced by an individual filling the
112
113
114
115
116
117
118
119
120
121
122
123
124
role of <i>Release Manager</i>, hereafter abbreviated as <i>RM</i>.  This
individual determines the schedule and executes the release processes
for the community.

@subsection releasewhohow RM Authority

Each release requires one individual to fulfill the RM role; however,
graceful transitions of this authority may take place at any time.  The
current RM may transfer their authority to another contributor in a post
to the OpenOCD development mailing list.  Such delegation of authority
must be approved by the individual that will receive it and the
community of maintainers.  Initial arrangements with the new RM should
be made off-list, as not every contributor wants these responsibilities.
125

126
@subsection releasewhowhat RM Responsibilities
127

128
129
130
131
132
133
134
135
136
137
138
In addition to the actual process of producing the releases, the RM is
responsible for keeping the community informed of all progress through
the release cycle(s) being managed.  The RM is responsible for managing
the changes to the package version, though the release tools should
manage the tasks of adding or removing any required development branch
tags and incrementing the version.

@section releasewhen Release Schedule

The OpenOCD release process must be carried out on a periodic basis, so
the project can realize the benefits presented in answer to the question,
139
@ref releasewhy.
140
141

Starting with the 0.2.0 release, the OpenOCD project should produce a
142
143
144
145
146
147
148
149
new minor release every month or two, with a major release once a year.
Bug fix releases could be provided more frequently.  These release
schedule goals may be adjusted in the future, after the project
maintainers and distributors receive feedback and experience.

More importantly, the statements made in this section do not create an
obligation by any member of the OpenOCD community to produce new
releases on regular schedule, now or in the future.
150

151
152
153
154
155
156
157
@subsection releasewhenexample Sample Schedule

The RM must pro-actively communicate with the community from the
beginning of the development cycle through the delivery of the new
release.  This section presents guidelines for scheduling key points
where the community must be informed of changing conditions.

158
If T is the time of the next release, then the following schedule
159
might describe some of the key milestones of the new release cycle:
160
161

- T minus one month: start of new development cycle
162
163
- T minus two weeks: announce pending mainline closure to new work
- T minus one week: close mainline to new work, begin testing phase
164
165
166
- T minus two days: call for final bug fixes
- T minus one day: produce -rc packages and distribute to testers
- T minus one hour: produce final packages and post on-line
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
- T minus zero: Announce the release to our mailing list and the world.

Some additional supplemental communication will be desirable.  The above
list omits the step-by-step instructions to daily release management.
Individuals performing release management need to have the ability to
interact proactively with the community as a whole, anticipating when
such interaction will be required and giving ample notification.

The next section explains why the OpenOCD project allows significant
flexibility in the part of the development that precedes the release
process.

@note The OpenOCD project does not presently produce -rc packages.  As
such, the step suggested in the list above should be read as trying to
stimulate others to test the project build and packaging on as many
platforms as possible.  This proposition will be palatable once release
management tools have been committed to the tree.

@subsection releasewhenflex Schedule Flexibility

The Release Manager should attempt to follow the guidelines in this
document, but the process of scheduling each release milestone should be
community driven at the start.  By the end, missing features that were
scheduled for a release must be dropped by the Release Manager, rather
than allowing the release cycle to be delayed while waiting for them.
192

193
194
Despite any assurances this schedule may appear to give, the Release
Manager cannot schedule the work that will be done on the project,
zwelch's avatar
zwelch committed
195
when it will be submitted, reviewed, and deemed suitable to be committed.
196
197
198
In this way, the RM cannot act as a priest in a cathedral; OpenOCD uses
the bazaar development model.  The release schedule must adapt
continuously in response to changes in the rate of churn.
199

200
201
202
203
204
In particular, the suggested period of "one or two month" reflects some
expectation of a fairly high rate of development.  Fewer releases may be
required if developers contribute less patches, and more releases may be
desirable if the project continues to grow and experience high rates of
community contribution.  During each cycle, the RM should be tracking
zwelch's avatar
zwelch committed
205
the situation and gathering feedback from the community.
206

207
208
209
210
211
212
213
@section releasehow Release Process: Step-by-Step

The release process may require a few iterations to work out any bugs.
Even with the release script, some steps require clear user intervention
-- and not only by the Release Manager.

The following steps should be followed to produce each release:
214

215
-# Produce final patches to mainline (or release branch):
216
  -# Finalize @c NEWS file to describe the changes in the release
217
218
219
    - This file is Used to automatically post "blurbs" about the project.
    - This material should be produced during the development cycle.
    - Add a new item for each @c NEWS-worthy contribution, when committed.
220
  -# bump library version if our API changed (not yet required)
221
  -# Remove -dev tag from package version in configure.in:
222
    - For major/minor releases, remove version tag from mainline, @a or
223
    - For bug-fix releases, remove version tag from release branch.
224
-# Branch or tag the required tree in the git repository:
225
226
  - Tags and branches for releases must be named consistently: @par
    "${PACKAGE_TARNAME}-${PACKAGE_VERSION}"
227
228
  - For a major/minor release from the mainline, the code should be
    tagged in the repository:
229
230
231
232
233
@verbatim
svn cp .../trunk .../branches/${RELEASE_BRANCH}
svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
@endverbatim
  - For bug-fix releases produced in their respective branch, a tag
234
    should be created in the repository:
235
236
237
238
@verbatim
svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
@endverbatim
-# Prepare to resume normal development activities:
239
240
  - Archive @c NEWS file as <code>doc/news/NEWS-${PACKAGE_VERSION}</code>.
  - Create a new @c NEWS file for the next release
241
242
243
  - For major/minor release from the mainline:
    -# Bump major or minor package version in mainline.
    -# Restore version tag to mainline.
244
245
246
  - For bug-fix releases from a release branch:
    -# Bump bug-fix version in release branch.
    -# Restore version tag to release branch.
247
248
249
-# Produce the package source archives:
  -# Start with a clean working copy, used for producing releases only.
  -# Switch to release tag branch: svn switch .../${RELEASE_TAG}
250
  -# Produce a ChangeLog for the release (using svn2cl).
251
252
253
  -# @c bootstrap, @c configure, and @c make the package.
  -# Run <code>make distcheck</code> to produce the distribution archives.
  -# Run <code>make maintainer-clean</code> verify the repository is empty.
254
  -# Create signature files using md5sum, sha1sum, etc.
255
256
257
-# Publish documentation for the release:
  - Allow users to access the documentation for each of our releases.
  - Place static copies of the following files on the project website:
258
259
    - @c NEWS: to provide a blurb for each release
    - @c ChangeLog: to show exactly what has been changed
260
    - User Guide, Developer Manual: to allow easy on-line viewing
261
-# Upload packages and post announcements of their availability:
262
263
264
265
266
267
  -# Release packages into files section of berliOS project site:
     -# Create the new release for the new version.
     -# Provide @c NEWS and ChangeLog files, as requested.
     -# Upload files via FTP to ftp://ftp.berlios.de/incoming/
     -# Edit descriptions for each file.
     -# Send E-mail Release Notice
268
  -# Post announcement e-mail to the openocd-development list.
269
  -# Announce updates on freshmeat.net and other trackers.
270
  -# Submit big updates to news feeds (e.g. Digg, Reddit, etc.).
271

272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
@section releasescript The Release Script

Many of the processes described in the last section are no longer
entrusted to humans.  Instead, the @c release.sh script provides
automation of the mechanical steps.

Presently, the @c release.sh script automates steps 1(c) through 4,
allowing the Release Manager from perform these tasks in easy steps.

The following task still need to be automated:

- Step 5: produce documentation for website using released source archive.
- Step 6(a): package archive upload process.
- Step 6(b): package announcement e-mail process.
- Step 6(c): post files and announce them using releaseforge.

In addition, support for '-rc' releases needs to be added.

@subsection releasescriptcmds Release Script Commands

The following output was taken from the release script:
@verbatim
294
usage: tools/release.sh [options] <command>
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312

Main Commands:
  info          Show a summary of the next pending release.
  release       Release the current tree as an archive.
  upload        Upload archives to berliOS project site

Build Commands:
  bootstrap     Prepare the working copy for configuration and building.
  configure     Configures the package; runs bootstrap, if needed.
  build         Compiles the project; runs configure, if needed.

Packaging Commands:
  changelog     Generate a new ChangeLog using svn2cl.
  package       Produce new distributable source archives.
  stage         Move archives to staging area for upload.

Repository Commands:
  commit        Perform branch and tag, as appropriate for the version.
313
  branch        Create a release branch from project mainline.
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
  tag           Create a tag for the current release branch.

Other Commands:
  version ...   Perform version number and tag manipulations.
  clean         Forces regeneration of results.
  clean_all     Removes all traces of the release process.
  help          Provides this list of commands.

For more information about this script, see the Release Processes page
in the OpenOCD Developer's Manual (doc/manual/release.txt).

WARNING: This script should be used by the Release Manager ONLY.
@endverbatim

Run <code>tools/release.sh help</code> for current command support.

zwelch's avatar
zwelch committed
330
@subsection releasescriptopts Release Script Options
331
332
333
334
335
336
337
338
339
340

The @c release.sh script recognizes some command-line options that
affect its behavior:

- @c --live : Use this option to perform a live release.
  When this option has been given, the release commands will affect
  the repository; otherwise, the script reports the actions to take,
  and it produces archives that are unsuitable for public release.

@note Only the Release Manager should use the @c --live option, as
341
it will make permanent changes to the git repository that
342
343
cannot be undone.

344
345
346
347
348
349
350
351
352
353
354
355
356
@subsection releasescriptenv Release Script Environment

The @c release.sh script recognizes some environment variables which
affect its behavior:

- @c CONFIG_OPTS : Passed as options to the configure script.
- @c MAKE_OPTS : Passed as options to the 'make' processes.

@section releasetutorial Release Tutorials

This section provides tutorials for using the Release Script to perform
common release tasks.

357
@subsection releasetutorialsetup Release Tutorial Setup
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373

The tutorials in this section assume the following environment
variables have been set properly:
@verbatim
SVN_USER="maintainer"
SVN_URL="https://${SVN_USER}@svn.berlios.de/svnroot/repos/openocd"
@endverbatim

@subsection releasetutorialminor Minor Release Tutorial

This section provides a step-by-step tutorial for a Release Manager to
use to run the @c release.sh script to produce a minor release.

If the proper environment has been set, the following steps will produce
a new minor release:

374
-# Check out (or update) mainline from the repository:
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
@code
svn checkout "${SVN_URL}/trunk" openocd-trunk
@endcode
-# Change to the new working copy directory:
@code
cd openocd-trunk
@endcode
-# Run @c release.sh to produce the minor release:
@code
tools/release.sh all
@endcode

@subsection releasetutorialmicro Bug-Fix Release Tutorial

This section provides a step-by-step tutorial for a Release Manager to
use to run the @c release.sh script to produce a bug-fix release.

In addition to the environment variables described in the introduction
to these tutorials, the following variables are also used in the
instructions for this section:
@verbatim
PACKAGE_BRANCH_VERSION="x.y.z"
PACKAGE_BRANCH="openocd-${PACKAGE_BRANCH_VERSION}"
@endverbatim

If the proper environment has been set, the following steps will produce
a new bug-fix release:

-# Check out (or update) the release branch from the project repository:
@code
svn checkout "${SVN_URL}/branches/${PACKAGE_BRANCH}" "${PACKAGE_BRANCH}"
@endcode
@code
cd "${PACKAGE_BRANCH}"
@endcode
-# Run @c release.sh to produce the bug-fix release:
@code
tools/release.sh all
@endcode

@section releasetodo Release Script Shortcomings

Improved automated packaging and distribution of OpenOCD requires more
patching of the configure script.  The final release script should be
able to manage most steps of the processes.  The steps requiring user
input could be guided by an "assistant" that walks the Release Manager
through the process from beginning to end, performing basic sanity
422
checks on their various inputs (e.g. the @c NEWS blurb).
423
424
425
426
427

 */
/** @file
This file contains the @ref releases page.
 */