Browse Source

Major update to release process documentation:

- Provide overview of OpenOCD versioning schema.
- Outline responsibilities and authority of the release manager.
- Explain the need for flexibility in the release schedule.
- Add and refine the release process steps.
- Include tutorials for using new release script.
- Many more improvements, too numerous to list.


git-svn-id: svn://svn.berlios.de/openocd/trunk@2462 b42882b7-edfa-0310-969c-e2dbd0fdcd60
tags/v0.2.0
zwelch 13 years ago
parent
commit
153270fea3
1 changed files with 319 additions and 56 deletions
  1. +319
    -56
      doc/manual/release.txt

+ 319
- 56
doc/manual/release.txt View File

@@ -1,21 +1,29 @@
/** @page releases Release Processes

This page provides an introduction to the OpenOCD Release Proceses:
- @ref releaseswhy
- @ref releaseswho
- @ref releaseswhen
- @ref releaseshow
This page provides an introduction to the OpenOCD Release Processes:

@section releaseswhy Why Produce Releases?
- @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.

The OpenOCD maintainers should produce releases periodically.
he reasons for several reasons that should be given in detail, before
explaining who and how the processes occur.
@section releasewhy Why Produce Releases?

The OpenOCD maintainers should produce <i>releases</i> periodically. This
section gives several reasons to explain the reasons for making releases
on a regular basis. These reasons lead to motivation for developing and
following a set of <i>release processes</i>. The actual processes are
described in the remainder of the @ref releases sections.

At any time, a "source archives" can be produced by running 'make dist'
in the OpenOCD project tree. With the 0.2.0 release, this command will
produce openocd-\<version\>.{tar.gz,tar.bz2,zip} archives, which will be
suitable for being released when produced properly.
produce openocd-\<version\>.{tar.gz,tar.bz2,zip} archives. These files
will be suitable for being released when produced properly.

When released for users, these archives present several important
advantages when contrasted to using the Subversion repository:
@@ -32,35 +40,100 @@ goals in mind. Specifically, the releases processes should have the
following properties:

-# Produce successive sets of release archives cleanly and consistently.
- Implementable as a script that automates the critical release steps.
-# Prevent human operators from doing it wrong, as much as possible.
-# Implementable as a script that automates the critical release steps.
-# Prevent human operators from producing bad releases, when possible.
-# Allow scheduling and automation of release process milestones.

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

@section releaseswho OpenOCD Release Manager
@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>).

The trunk and all branches should have the tag '-in-development' in
their version number. This tag helps developers identify reports
created from the Subversion repository, and it can be detected and
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.

@subsection releaseversionsdist Patched Versions

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

@subsection releaseversionsdist Version Processes

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.

The version numbers for any branch should monotonically
increase to the next successive integer, except when reset to zero
during major or minor releases. The community should decide when
major and minor milestones will be released.

@section releasewho Release Manager

OpenOCD archive releases will be produced by an individual filling the
role of <i>Release Manager</i>. This individual determines the schdule
(@see releaseswhen) and executes the release processes for the
community. Each release requires one individual to fulfill this role,
and these processes should survive any such transition gracefully.
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.

@section releaseswhen OpenOCD Release Schedule
@subsection releasewhowhat RM Responsibilities

The OpenOCD release process must be carried out on a periodic basis
in order to realize the benefits outlined above (@see releaseswhy).
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,
@ref releasewhy.

Starting with the 0.2.0 release, the OpenOCD project should produce a
new minor release each month, with a major release once per year. Bug
fix releases could be provided more frequently; however, these should
not be a priority for the Release Manager until the processes have been
fully automated, to use resources most efficiently.
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.

If T is the time of the next release, then the following milestones
describe the release milestones for each new release cycle.
@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.

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

- T minus one month: start of new development cycle
- T minus two weeks: announce pending trunk closure to new work
@@ -68,25 +141,62 @@ describe the release milestones for each new release cycle.
- 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
- 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.

The process of scheduling release milestones should be community driven,
though the Release Manager should attempt to follow these guidelines.
Specifically, missing features that were scheduled for a release should
be dropped, rather than delaying the release cycle to wait for them.
Despite any assurances this schedule may appear to give, the Release
Manager cannot schedule the work that will be done on the project,
when it will be submitted, review, and deemed suitable to be committed.
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.

@section releaseshow Release Process: Step-by-Step
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
the situation and gathering feedback from the community .

The exact process likely requires a few releases to work out the bugs,
as it will take some experience before a script can be developed and
tested that does everything safely and robustly. Even then, some steps
require clear user intervention -- and not only by the release manager.
@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:

-# Produce final patches to the trunk (or release branch):
- add NEWS item to describe the release changes? (not ready for 0.2.0)
-# add NEWS item to describe the release changes? (not ready for 0.2.0)
- the community should try to help produce this material
- can be used to automatically post "blurbs" about the project.
- bump library version if our API changed (not yet required)
- bump package version
-# bump library version if our API changed (not yet required)
-# Remove -in-development tag from package version:
- For major/minor releases, remove version tag from trunk.
- For bug-fix releases, remove version tag from release branch.
-# Produce and verify the binary packages:
-# Start with a clean working copy, used for producing releases only.
-# produce a ChangeLog for the release (using svn2cl).
@@ -94,27 +204,180 @@ require clear user intervention -- and not only by the release manager.
-# run 'make distcheck' to produce the distribution archives.
-# run 'make maintainer-clean'; verify the repository is empty again.
-# Branch or tag the required tree in the Subversion repository:
- For a major/minor release from the main trunk, branch and tag it:
-# svn cp .../trunk .../branches/${BRANCH_VERSION}
-# svn cp .../branches/${BRANCH_VERSION} .../tags/${PACKAGE_VERSION}
- For a bug-fix or final release from a release branch, only tag it:
-# svn cp .../branches/${BRANCH_VERSION} .../tags/${PACKAGE_VERSION}
- where:
- BRANCH_VERSION - is x.0.0-trunk or x.y.0-trunk
- PACKAGE_VERSION - is x.y.z
- Tags and branches for releases must be named consistently: @par
"${PACKAGE_TARNAME}-${PACKAGE_VERSION}"
- For a major/minor release from the main trunk, the code should be
branched and tagged in the repository:
@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
should be created in the repository:
@verbatim
svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
@endverbatim
-# Prepare to resume normal development activities:
- For major/minor release from the trunk:
-# Bump major or minor package version in trunk.
-# Restore version tag to trunk and release branch.
- For bug-fix releases from a release branch:
-# Bump bug-fix version in release branch.
-# Restore version tag to release branch.
-# 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:
- NEWS: to provide a blurb for each release (not yet used)
- ChangeLog: to show exactly what has been changed
- User Guide, Developer Manual: to allow easy on-line viewing
-# Upload packages and post announcements of their availability:
-# Release packages into files section of berliOS project site.
-# Post announcement e-mail to the openocd-development list.
-# After the community has checked their sanity, we can post "blurbs":
-# Post NEWS update to freshmeat.net and other trackers.
-# Announce updates on freshmeat.net and other trackers.
-# Submit big NEWS updates to news feeds (e.g. Digg, Reddit, etc.).

Totally-automated packaging and distribution of OpenOCD requires more
patching (post-0.2.0), but the final script(s) should be able to manage
most steps in these processes. The steps requiring user input can be
guided by an "assistant" that walks the Release Manager through the
process from beginning to end, performing basic sanity checks on their
various inputs (e.g. the NEWS blurb).
@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
usage: tools/release.sh <command>

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.
branch Create a release branch from the project trunk.
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.

@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.
- @c RELEASE_DRY_RUN : Set this to null to perform the live release.
Unless this variable has been (un)set, the release commands will not
affect the repository.

Proper option handling should be added to set these variables in script.

@section releasetutorial Release Tutorials

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

@subsection releasetutorialminor Minor Release Tutorial

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:

-# Check out (or update) the project trunk from the berliOS repository:
@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
checks on their various inputs (e.g. the NEWS blurb).

*/
/** @file


Loading…
Cancel
Save