|
- /** @page releases Release Processes
-
- This page provides an introduction to the OpenOCD Release Processes:
-
- - @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.
-
- @section releasewhy Why Produce Releases?
-
- 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.
-
- 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.
-
- When released for users, these archives present several important
- advantages when contrasted to using the git repository:
-
- -# They allow others to package and distribute the code.
- -# They build easier for developers, because they contain
- a working configure script that was produced by the Release Manager.
- -# They prevent users from trying a random work-in-process revision.
- -# They free developers from answering questions about mainline breakage.
-
- Hopefully, this shows several good reasons to produce regular releases,
- but the release processes were developed with some additional design
- goals in mind. Specifically, the releases processes should have the
- following properties:
-
- -# 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.
-
- The current release processes are documented in the following sections.
- They attempt to meet these design goals, but there may improvements
- remaining to be made toward automating the process.
-
- @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>).
-
- @subsection releaseversiontags Version Tags
-
- After these required numeric components, the version string may contain
- one or more <i>version tags</i>, such as '-rc1' or '-dev'.
-
- Mainline and all branches should have the tag '-dev' in
- their version number. This tag helps developers identify reports
- created from the git 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.
-
- 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
-
- 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.
-
- @subsection releaseversionhow 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 increase monotonically
- 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>, 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.
-
- @subsection releasewhowhat RM Responsibilities
-
- 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 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.
-
- @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 mainline closure to new work
- - T minus one week: close mainline to new work, begin testing phase
- - 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.
-
- 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, reviewed, 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.
-
- 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.
-
- @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 mainline (or release branch):
- -# Finalize @c NEWS file to describe the changes in the release
- - 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.
- -# bump library version if our API changed (not yet required)
- -# Remove -dev tag from package version in configure.in:
- - For major/minor releases, remove version tag from mainline, @a or
- - For bug-fix releases, remove version tag from release branch.
- -# Branch or tag the required tree in the git repository:
- - Tags and branches for releases must be named consistently: @par
- "${PACKAGE_TARNAME}-${PACKAGE_VERSION}"
- - For a major/minor release from the mainline, the code should be
- 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:
- - Archive @c NEWS file as <code>doc/news/NEWS-${PACKAGE_VERSION}</code>.
- - Create a new @c NEWS file for the next release
- - For major/minor release from the mainline:
- -# Bump major or minor package version in mainline.
- -# Restore version tag to mainline.
- - For bug-fix releases from a release branch:
- -# Bump bug-fix version in release branch.
- -# Restore version tag to release branch.
- -# 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}
- -# Produce a ChangeLog for the release (using svn2cl).
- -# @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.
- -# Create signature files using md5sum, sha1sum, etc.
- -# 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:
- - @c NEWS: to provide a blurb for each release
- - @c 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:
- -# 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
- -# Post announcement e-mail to the openocd-development list.
- -# Announce updates on freshmeat.net and other trackers.
- -# Submit big updates to news feeds (e.g. Digg, Reddit, etc.).
-
- @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 [options] <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 project mainline.
- 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 releasescriptopts Release Script Options
-
- 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
- it will make permanent changes to the git repository that
- cannot be undone.
-
- @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.
-
- @subsection releasetutorialsetup Release Tutorial Setup
-
- 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) mainline from the 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 @c NEWS blurb).
-
- */
- /** @file
- This file contains the @ref releases page.
- */
|