[openocd.git] / doc / manual / release.txt
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 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.
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.
28 When released for users, these archives present several important
29 advantages when contrasted to using the Subversion repository trunk:
31 -# They allow others to package and distribute the code.
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 the release processes were developed with some additional design
39 goals in mind. Specifically, the releases processes should have the
40 following properties:
42 -# Produce successive sets of archives cleanly and consistently.
43 -# Implementable as a script that automates the critical steps.
44 -# Prevent human operators from producing broken packages, when possible.
45 -# Allow scheduling and automation of building and publishing 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 @subsection releaseversiontags Version Tags
64 After these required numeric components, the version string may contain
65 one or more <i>version tags</i>, such as '-rc1' or '-dev'.
67 The trunk and all branches should have the tag '-dev' in
68 their version number. This tag helps developers identify reports
69 created from the Subversion repository, and it can be detected and
70 manipulated by the release script. Specifically, this tag will be
71 removed and re-added during the release process; it should never be
72 manipulated by developers in submitted patches.
74 The 'rc' tags indicate a "release candidate" version of the package.
75 This tag will also be manipulated by the automated release process.
77 Additional tags may be used as necessary.
79 @subsection releaseversionsdist Packager Versions
81 Distributors of patched versions of OpenOCD are encouraged to extend the
82 version string with a unique version tag when producing external
83 releases, as this helps to identify your particular distribution series.
85 For example, the following command will add a 'foo1' tag to the
86 configure.in script of a local copy of the source tree:
88 @code
89 tools/release.sh version bump tag foo
90 @endcode
92 This command will modify the configure.in script in your working copy
93 only. After running the @c bootstrap sequence, the tree can be patched
94 and used to produce your own derived versions. The same command can be
95 used each time the derived package is released, incrementing the tag's
96 version to facilitate tracking the changes you have distributed.
98 @subsection releaseversionhow Version Processes
100 The release process includes version number manipulations to the tree
101 being released, ensuring that all numbers are incremented at the right
102 time and in the proper locations of the repository.
104 The version numbers for any branch should increase monotonically
105 to the next successive integer, except when reset to zero
106 during major or minor releases. The community should decide when
107 major and minor milestones will be released.
109 @section releasewho Release Manager
111 OpenOCD archive releases will be produced by an individual filling the
112 role of <i>Release Manager</i>, hereafter abbreviated as <i>RM</i>. This
113 individual determines the schedule and executes the release processes
114 for the community.
116 @subsection releasewhohow RM Authority
118 Each release requires one individual to fulfill the RM role; however,
119 graceful transitions of this authority may take place at any time. The
120 current RM may transfer their authority to another contributor in a post
121 to the OpenOCD development mailing list. Such delegation of authority
122 must be approved by the individual that will receive it and the
123 community of maintainers. Initial arrangements with the new RM should
124 be made off-list, as not every contributor wants these responsibilities.
126 @subsection releasewhowhat RM Responsibilities
128 In addition to the actual process of producing the releases, the RM is
129 responsible for keeping the community informed of all progress through
130 the release cycle(s) being managed. The RM is responsible for managing
131 the changes to the package version, though the release tools should
132 manage the tasks of adding or removing any required development branch
133 tags and incrementing the version.
135 @section releasewhen Release Schedule
137 The OpenOCD release process must be carried out on a periodic basis, so
138 the project can realize the benefits presented in answer to the question,
139 @ref releasewhy.
141 Starting with the 0.2.0 release, the OpenOCD project should produce a
142 new minor release every month or two, with a major release once a year.
143 Bug fix releases could be provided more frequently. These release
144 schedule goals may be adjusted in the future, after the project
145 maintainers and distributors receive feedback and experience.
147 More importantly, the statements made in this section do not create an
148 obligation by any member of the OpenOCD community to produce new
149 releases on regular schedule, now or in the future.
151 @subsection releasewhenexample Sample Schedule
153 The RM must pro-actively communicate with the community from the
154 beginning of the development cycle through the delivery of the new
155 release. This section presents guidelines for scheduling key points
156 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:
161 - T minus one month: start of new development cycle
162 - T minus two weeks: announce pending trunk closure to new work
163 - T minus one week: close trunk to new work, begin testing phase
164 - T minus two days: call for final bug fixes
165 - T minus one day: produce -rc packages and distribute to testers
166 - T minus one hour: produce final packages and post on-line
167 - T minus zero: Announce the release to our mailing list and the world.
169 Some additional supplemental communication will be desirable. The above
170 list omits the step-by-step instructions to daily release management.
171 Individuals performing release management need to have the ability to
172 interact proactively with the community as a whole, anticipating when
173 such interaction will be required and giving ample notification.
175 The next section explains why the OpenOCD project allows significant
176 flexibility in the part of the development that precedes the release
177 process.
179 @note The OpenOCD project does not presently produce -rc packages. As
180 such, the step suggested in the list above should be read as trying to
181 stimulate others to test the project build and packaging on as many
182 platforms as possible. This proposition will be palatable once release
183 management tools have been committed to the tree.
185 @subsection releasewhenflex Schedule Flexibility
187 The Release Manager should attempt to follow the guidelines in this
188 document, but the process of scheduling each release milestone should be
189 community driven at the start. By the end, missing features that were
190 scheduled for a release must be dropped by the Release Manager, rather
191 than allowing the release cycle to be delayed while waiting for them.
193 Despite any assurances this schedule may appear to give, the Release
194 Manager cannot schedule the work that will be done on the project,
195 when it will be submitted, reviewed, and deemed suitable to be committed.
196 In this way, the RM cannot act as a priest in a cathedral; OpenOCD uses
197 the bazaar development model. The release schedule must adapt
198 continuously in response to changes in the rate of churn.
200 In particular, the suggested period of "one or two month" reflects some
201 expectation of a fairly high rate of development. Fewer releases may be
202 required if developers contribute less patches, and more releases may be
203 desirable if the project continues to grow and experience high rates of
204 community contribution. During each cycle, the RM should be tracking
205 the situation and gathering feedback from the community.
207 @section releasehow Release Process: Step-by-Step
209 The release process may require a few iterations to work out any bugs.
210 Even with the release script, some steps require clear user intervention
211 -- and not only by the Release Manager.
213 The following steps should be followed to produce each release:
215 -# Produce final patches to the trunk (or release branch):
216 -# Finalize @c NEWS file to describe the changes in the release
217 - This file is Used to automatically post "blurbs" about the project.
218 - This material should be produced during the development cycle.
219 - 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 trunk, @a or
223 - For bug-fix releases, remove version tag from release branch.
224 -# Branch or tag the required tree in the Subversion repository:
225 - Tags and branches for releases must be named consistently: @par
227 - For a major/minor release from the main trunk, the code should be
228 branched and tagged in the repository:
229 @verbatim
230 svn cp .../trunk .../branches/${RELEASE_BRANCH}
231 svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
232 @endverbatim
233 - For bug-fix releases produced in their respective branch, a tag
234 should be created in the repository:
235 @verbatim
236 svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
237 @endverbatim
238 -# Prepare to resume normal development activities:
239 - Archive @c NEWS file as <code>doc/news/NEWS-${PACKAGE_VERSION}</code>.
240 - Create a new @c NEWS file for the next release
241 - For major/minor release from the trunk:
242 -# Bump major or minor package version in trunk.
243 -# Restore version tag to trunk and release branch.
244 - For bug-fix releases from a release branch:
245 -# Bump bug-fix version in release branch.
246 -# Restore version tag to release branch.
247 -# Produce the package source archives:
248 -# Start with a clean working copy, used for producing releases only.
249 -# Switch to release tag branch: svn switch .../${RELEASE_TAG}
250 -# Produce a ChangeLog for the release (using svn2cl).
251 -# @c bootstrap, @c configure, and @c make the package.
252 -# Run <code>make distcheck</code> to produce the distribution archives.
253 -# Run <code>make maintainer-clean</code> verify the repository is empty.
254 -# Create signature files using md5sum, sha1sum, etc.
255 -# Publish documentation for the release:
256 - Allow users to access the documentation for each of our releases.
257 - Place static copies of the following files on the project website:
258 - @c NEWS: to provide a blurb for each release
259 - @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 -# Release packages into files section of berliOS project site:
263 -# Create the new release for the new version.
264 -# Provide @c NEWS and ChangeLog files, as requested.
265 -# Upload files via FTP to ftp://ftp.berlios.de/incoming/
266 -# Edit descriptions for each file.
267 -# 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.).
272 @section releasescript The Release Script
274 Many of the processes described in the last section are no longer
275 entrusted to humans. Instead, the @c release.sh script provides
276 automation of the mechanical steps.
278 Presently, the @c release.sh script automates steps 1(c) through 4,
279 allowing the Release Manager from perform these tasks in easy steps.
281 The following task still need to be automated:
283 - Step 5: produce documentation for website using released source archive.
284 - Step 6(a): package archive upload process.
285 - Step 6(b): package announcement e-mail process.
286 - Step 6(c): post files and announce them using releaseforge.
288 In addition, support for '-rc' releases needs to be added.
290 @subsection releasescriptcmds Release Script Commands
292 The following output was taken from the release script:
293 @verbatim
294 usage: tools/release.sh [options] <command>
296 Main Commands:
297 info Show a summary of the next pending release.
298 release Release the current tree as an archive.
299 upload Upload archives to berliOS project site
301 Build Commands:
302 bootstrap Prepare the working copy for configuration and building.
303 configure Configures the package; runs bootstrap, if needed.
304 build Compiles the project; runs configure, if needed.
306 Packaging Commands:
307 changelog Generate a new ChangeLog using svn2cl.
308 package Produce new distributable source archives.
309 stage Move archives to staging area for upload.
311 Repository Commands:
312 commit Perform branch and tag, as appropriate for the version.
313 branch Create a release branch from the project trunk.
314 tag Create a tag for the current release branch.
316 Other Commands:
317 version ... Perform version number and tag manipulations.
318 clean Forces regeneration of results.
319 clean_all Removes all traces of the release process.
320 help Provides this list of commands.
322 For more information about this script, see the Release Processes page
323 in the OpenOCD Developer's Manual (doc/manual/release.txt).
325 WARNING: This script should be used by the Release Manager ONLY.
326 @endverbatim
328 Run <code>tools/release.sh help</code> for current command support.
330 @subsection releasescriptopts Release Script Options
332 The @c release.sh script recognizes some command-line options that
333 affect its behavior:
335 - @c --live : Use this option to perform a live release.
336 When this option has been given, the release commands will affect
337 the repository; otherwise, the script reports the actions to take,
338 and it produces archives that are unsuitable for public release.
340 @note Only the Release Manager should use the @c --live option, as
341 it will make permanent changes to the Subversion repository that
342 cannot be undone.
344 @subsection releasescriptenv Release Script Environment
346 The @c release.sh script recognizes some environment variables which
347 affect its behavior:
349 - @c CONFIG_OPTS : Passed as options to the configure script.
350 - @c MAKE_OPTS : Passed as options to the 'make' processes.
352 @section releasetutorial Release Tutorials
354 This section provides tutorials for using the Release Script to perform
355 common release tasks.
357 @subsection releasetutorialsetup Release Tutorial Setup
359 The tutorials in this section assume the following environment
360 variables have been set properly:
361 @verbatim
362 SVN_USER="maintainer"
363 SVN_URL="https://${SVN_USER}@svn.berlios.de/svnroot/repos/openocd"
364 @endverbatim
366 @subsection releasetutorialminor Minor Release Tutorial
368 This section provides a step-by-step tutorial for a Release Manager to
369 use to run the @c release.sh script to produce a minor release.
371 If the proper environment has been set, the following steps will produce
372 a new minor release:
374 -# Check out (or update) the project trunk from the berliOS repository:
375 @code
376 svn checkout "${SVN_URL}/trunk" openocd-trunk
377 @endcode
378 -# Change to the new working copy directory:
379 @code
380 cd openocd-trunk
381 @endcode
382 -# Run @c release.sh to produce the minor release:
383 @code
384 tools/release.sh all
385 @endcode
387 @subsection releasetutorialmicro Bug-Fix Release Tutorial
389 This section provides a step-by-step tutorial for a Release Manager to
390 use to run the @c release.sh script to produce a bug-fix release.
392 In addition to the environment variables described in the introduction
393 to these tutorials, the following variables are also used in the
394 instructions for this section:
395 @verbatim
398 @endverbatim
400 If the proper environment has been set, the following steps will produce
401 a new bug-fix release:
403 -# Check out (or update) the release branch from the project repository:
404 @code
405 svn checkout "${SVN_URL}/branches/${PACKAGE_BRANCH}" "${PACKAGE_BRANCH}"
406 @endcode
407 @code
408 cd "${PACKAGE_BRANCH}"
409 @endcode
410 -# Run @c release.sh to produce the bug-fix release:
411 @code
412 tools/release.sh all
413 @endcode
415 @section releasetodo Release Script Shortcomings
417 Improved automated packaging and distribution of OpenOCD requires more
418 patching of the configure script. The final release script should be
419 able to manage most steps of the processes. The steps requiring user
420 input could be guided by an "assistant" that walks the Release Manager
421 through the process from beginning to end, performing basic sanity
422 checks on their various inputs (e.g. the @c NEWS blurb).
424 */
425 /** @file
426 This file contains the @ref releases page.
427 */

Linking to existing account procedure

If you already have an account and want to add another login method you MUST first sign in with your existing account and then change URL to read https://review.openocd.org/login/?link to get to this page again but this time it'll work for linking. Thank you.

SSH host keys fingerprints

1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=..              |
|+o..   .         |
|*.o   . .        |
|+B . . .         |
|Bo. = o S        |
|Oo.+ + =         |
|oB=.* = . o      |
| =+=.+   + E     |
|. .=o   . o      |
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)