@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.
+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, 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. These files
-will be suitable for being released when produced properly.
+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 Subversion repository:
+advantages when contrasted to using the git repository:
--# They allow others to package and distribute the code to users.
+-# 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 HEAD revision of the trunk.
--# They free developers from answering questions about trunk breakage.
+-# 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 these release processes were developed with some additional design
+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 release archives cleanly and consistently.
--# 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.
+-# 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
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
+@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 Subversion repository, and it can be detected and
+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.
-@subsection releaseversionsdist Patched Versions
+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:
-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.
+@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 releaseversionsdist Version Processes
+@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 monotonically
-increase to the next successive integer, except when reset to zero
+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.
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.
+@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.
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
+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
-- T minus one week: close trunk to new work, begin testing phase
+- 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
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.
+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.
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 situation and gathering feedback from the community.
@section releasehow Release Process: Step-by-Step
The following steps should be followed to produce each release:
--# Produce final patches to the trunk (or release branch):
- -# Finalize @c NEWS file to describe the changes in the release
+-# Produce final manual 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 -in-development tag from package version:
- - For major/minor releases, remove version tag from trunk, @a or
- - For bug-fix releases, remove version tag from release branch.
--# Branch or tag the required tree in the Subversion repository:
- - 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:
+ -# Bump library version if our API changed (not yet required)
+-# Produce and tag the final revision in the git repository:
+ - Update and commit the final package version in @c configure.in :
+ -# Remove @c -dev tag.
+ -# Remove @c -rc tag, if producing the final release from an -rc series.
+ - Tags must be named consistently:
@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:
+ - Tag the final commit with a consistent GIT tag name and message:
@verbatim
-svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
+PACKAGE_VERSION="x.y.z"
+PACKAGE_TAG="v${PACKAGE_VERSION}"
+git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_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 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.
+-# Prepare to resume normal development on the branch:
+ - Restore @c -dev and -@c -rc0 version tags.
+ - To start a new major (or minor) release cycle on the @c master branch:
+ - Bump major (or minor) package version, zeroing sub-components.
+ - Add -rc0 version tag:
+ - This insures casual releases from GIT always increase monotonically.
+ - For example, a major increment after releasing 1.2.3 starts 2.0.0-rc0-dev.
+ - Archive @c NEWS file as "<code>doc/news/NEWS-${PACKAGE_VERSION}</code>".
+ - Create a new @c NEWS file for the next release
+ - To start a bug-fix release on a non-master branch:
+ -# Bump bug-fix version.
+ - To start another release candidate on a major or minor branch:
+ -# Bump rc tag.
-# 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).
+ -# Checkout the appropriate tag:
+<code>git checkout $(git tag ) "${PACKAGE_VERSION}"</code>
+ -# Produce a ChangeLog for the release (using @c git2cl).
-# @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 @c md5sum, @c 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 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:
+ -# Release packages into files section of project sites:
+ - SF.net:
+ -# Create a new folder named "${PACKAGE_VERSION}"
+ -# Select new folder as the target for uploads.
+ -# Upload files via Web interface into new
+ -# Set platform types for each archive:
+ - .tar.bz2: Linux, Mac
+ - .tar.gz: BSD, Solaris, Others
+ - .zip: Windows
+ - Berlios:
-# 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
+ -# Click button to 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.).
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,
+Presently, the @c release.sh script automates steps 2 through 4,
allowing the Release Manager from perform these tasks in easy steps.
The following task still need to be automated:
- 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
+The release script can be used for two tasks:
+- Creating releases and starting a new release cycle:
+@code
+git checkout master
+tools/release.sh --type=minor --final --start-rc release
+@endcode
+- Creating a development branch from a tagged release:
+@code
+git checkout 'v0.2.0'
+tools/release.sh --type=micro branch
+@endcode
+
+Both of these variations make automatic commits and tags in your
+repository, so you should be sure to run it on a cloned copy before
+proceding with a live release.
+
+@subsection releasescriptopts Release Script Options
-Run <code>tools/release.sh help</code> for current command support.
+The @c release.sh script recognizes some command-line options that
+affect its behavior:
+
+- The @c --start-rc indicates that the new development release cycle
+ should start with @c -rc0. Without this, the @c -rc tag will be omitted,
+ leading to non-monotonic versioning of the in-tree version numbers.
+- The @c --final indicates that the release should drop the @c -rc tag,
+ to going from @c x.y.z-rcN-dev to x.y.z.
@subsection releasescriptenv Release Script Environment
- @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
+This section should contain a brief tutorial for using the Release
+Script to perform release tasks, but the new script needs to be
+used for 0.3.0.
@section releasetodo Release Script Shortcomings
projects / fw / openocd / blobdiff