/** @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 releasescriptcmds - 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?
-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.
+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.
-When released for users, these archives present several important
-advantages when contrasted to using the Subversion repository:
+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.
--# They allow others to package and distribute the code to users.
--# 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.
+When properly versioned and released for users, these archives present
+several important advantages compared to using the source repository
+(including snapshots downloaded from that repository using gitweb):
+
+-# They allow others to package and distribute the code using
+ consistent version labels. Users won't normally need to care
+ whose package they use, just the version of OpenOCD.
+-# They contain a working configure script and makefiles, which
+ were produced as part of creating the archive.
+-# Because they have been formally released by the project, users
+ don't need to try a random work-in-process revision. Releasing
+ involves spending some time specifically on quality improvments,
+ including bugfixing source code and documentation.
+-# They provide developers with the flexibility needed to address
+ larger issues, which sometimes involves temporary 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 doing it wrong, as much as 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 are many improvements
-remaining to be made toward automating the process.
+They attempt to meet these design goals, but improvements may still
+need to be made.
+
+@subsection version_labels Version Labels
+
+Users can display the OpenOCD version string in at least two
+ways. The command line <code>openocd -v</code> invocation
+displays it; as does the Tcl <code>version</code> command.
+
+Labels for released versions look like <em>0.3.0</em>, or
+<em>0.3.0-rc1</em> for a preliminary release.
+Non-released (developer) versions look like <em>0.3.0-dev</em>,
+or <em>0.3.0-rc1-dev</em>.
+In all cases, additional tags may be appended to those base
+release version labels.
+
+The <code>tools/release/version.sh</code> script is used to
+manipulate version IDs found in the source tree.
+
+@subsubsection releaseversions Release Versions and Tags
+
+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 any <em>bug-fix</em> 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>).
+
+After these required numeric components, release version strings
+may contain tags such as as <em>-rc1</em> or <em>-rc2</em>.
+These 'rc' tags indicate "release candidate" versions of the package.
+Like major/minor/micro numbers, these are updated
+as part of the release process.
+
+The release process includes version number manipulations to the tree
+being released, ensuring that all numbers are incremented (or rolled
+over) at the right time and in the proper locations of the repository.
+One of those manipulations creates a repository tag matching that
+release's version label.
+
+@subsubsection 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.
+Knowing that a release has such patches can be essential to tracking
+down and fixing bugs.
+
+Packager version tags should always be suffixes to the version
+code from the OpenOCD project, signifying modifications to the
+original code base. Each packager release should have a unique
+version.
+
+For example, the following command will add a 'foo' tag to the
+configure.ac script of a local copy of the source tree, giving
+a version label like <em>0.3.0-foo</em>:
+
+@code
+tools/release/version.sh version tag add foo
+@endcode
+
+This command will modify the configure.ac 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. You might check that
+change into a private branch of your git tree, along with the other
+patches you are providing.
+
+You can also "bump" those tags (so "foo1" becomes "foo2" etc)
+each time a derived package is released, incrementing the tag's
+version to facilitate tracking the changes you have distributed.
-@section releaseswho OpenOCD Release Manager
+@code
+tools/release/version.sh version bump tag foo
+@endcode
+
+Of course, any patches in your branches must be provided to
+your customers, and be in conformance with the GPL. In most
+cases you should also work to merge your improvements to the
+mainline tree.
+
+@subsubsection version_tags Development Versions and Tags
+
+Everything except formal releases should have the tag <em>-dev</em>
+in their version number. This helps developers identify reports
+created from non-release versions, 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.
+
+Versions built from developer trees may have additional tags.
+Trees built from git snapshots have <em>snapshot</em> tags.
+When built from a "live" git tree, tags specify
+specific git revisions:
+
+0.3.0-rc1-dev-00015-gf37c9b8-dirty
+
+indicates a development tree based on git revison f37c9b8
+(a truncated version of a SHA1 hash) with some non-git
+patches applied (the <em>dirty</em> tag). This information
+can be useful when tracking down bugs.
+(Note that at this writing, the tags do not directly
+correspond to <code>git describe</code> output. The
+hash ID can be used with <code>git show</code>, but
+the relevant repository tag isn't <em>0.3.0-rc1-dev</em>;
+this might change in the future.)
+
+@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.
-
-@section releaseswhen OpenOCD Release Schedule
-
-The OpenOCD release process must be carried out on a periodic basis
-in order to realize the benefits outlined above (@see releaseswhy).
-
-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.
-
-If T is the time of the next release, then the following milestones
-describe the release milestones for each 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 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
-
-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.
-
-@section releaseshow Release Process: Step-by-Step
-
-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.
-
--# Produce final patches to the trunk (or release branch):
- - 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
--# 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).
- -# bootstrap, configure, and build the package.
- -# 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
+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.
+
+These responsibilities matter most towards the end of the release
+cycle, when the RM creates the first RC and all contributors enter
+a quality-improvement mode. The RM works with other contributors
+to make sure everyone knows what kinds of fixes should merge, the
+status of major issues, and the release timetable.
+
+In particular, the RM has the final decision on whether a given
+bug should block the release.
+
+@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 expects to produce
+new releases every few months.
+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 Tn is the time of release n, then the following schedule
+might describe some key T0-to-T1 release cycle milestones.
+
+- T0 ... End of T0 release cycle. T1 cycle starts, with merge
+ window opening. Developers begin to merge queued work.
+- <em>... several weeks of merge window ...</em>
+- RC1 ... Close mainline to new work. Produce RC1
+ release, begin testing phase; developers are in "bugfix mode",
+ all other work is queued; send out planned endgame schedule.
+- RC2 ... Produce RC2 and send schedule update to
+ mailing list, listing priorities for remaining fixes
+- <em>... more RC milestones, until ready ...</em>
+- T1: End of T1 release cycle. T2 cycle starts, with merge
+ window opening. Developers begin to merge queued work.
+
+Note that until it happens, any date for T1 is just a goal.
+Critical bugs prevent releases from happening. We are just
+beginning to use this window-plus-RCs process, so the lengths
+of the merge windows versus the RC phase is subject to change.
+Most projects have RC phases of a month or more.
+
+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.
+
+@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. Features that don't complete before
+the merge window closes can be held (perhaps in some branch) until
+the next merge window opens, rather than delaying the release cycle.
+
+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.
+That is, 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 work.
+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 is not final; it may need more iterations
+to work out bugs.
+While there are release scripts, key steps require community
+support; the Release Manager isn't the only participant.
+
+The following steps should be followed to produce each release:
+
+-# Produce final patches using a local clone of mainline. Nobody
+ except the RM should be committing anything. <em>Everyone with commit
+ privileges needs to know and agree to this in advance!</em> Even the RM
+ only commits a handful of updates as part of the release process
+ itself ... to files which are part of the version identification scheme
+ or release process; and to create the version tag; and then to open the
+ merge window for the next release cycle.
+ -# Finalize @c the NEWS file to describe the changes in the release
+ - This file is used to automatically post "blurbs" about the project.
+ - This material should have been produced during the development cycle,
+ by adding items for each @c NEWS-worthy contribution, when committed
+ during the merge window. (One part of closing the merge window, by
+ opening the RC phase of the release, is the commitment to hold all
+ further such contributions until the next merge window opens.)
+ - The RM should make sure nothing important was omitted, as part of
+ the RC1 cycle. From then on, no more updates to NEWS content should
+ be needed (except to seed the process for the next release, or maybe
+ if a significant and longstanding bug is fixed late in the RC phase).
+ -# Bump library version if our API changed (not yet required)
+ -# Update and commit the final package version in @c configure.ac:
+ (The <code>tools/release/version.sh</code> script might help ensure
+ the versions are named properly.):
+ -# Remove @c -dev tag.
+ -# Update any @c -rc tag:
+ - If producing the final release from an -rc series, remove it
+ - If producing the first RC in a series, add rc1
+ - If producing the next RC in a series, bump the rc number
+ -# Commit that version change, with a good descriptive comment.
+ -# Create a git tag for the final commit, with a tag name matching
+ the version string in <code>configure.ac</code> (including <em>-rcN</em>
+ where relevant):
+@verbatim
+PACKAGE_VERSION="x.y.z"
+PACKAGE_TAG="v${PACKAGE_VERSION}"
+git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}"
+@endverbatim
+ -# Do not push those changes to mainline yet; only builds using the
+ source archives you will be creating should ever be labeled as
+ official releases (with no "-dev" suffix). Since mainline is a
+ development tree, these will be pushed later, as part of opening
+ the merge window for the next release cycle (restoring the "-dev"
+ suffix for that next release.) Those version and tag updates are
+ the last ones to be included in the release being made.
+-# Produce the release files, using the local clone of the source
+ tree which holds the release's tag and updated version in
+ @c configure.ac ... this is used only to produce the release, and
+ all files should already be properly checked out.
+ -# Run <code>tools/release.sh package</code> to produce the
+ source archives. This automatically bootstraps and
+ configures the process.
+ -# Run <code>tools/release.sh stage</code> to create an @c archives
+ directory with the release data, including MD5 and SHA1
+ checksum files.
+ -# Sanity check at least one of those archives, by extracting and
+ configuring its contents, using them to build a copy of OpenOCD,
+ and verifying that the result prints the correct release version
+ in its startup banner. (For example,
+ "configure --enable-ft2232_libftdi --enable-parport"
+ then "make" and run "src/openocd -v" as a sanity check.)
+ -# Run <code>make docs</code> to create the
+ documentation which will be published.
-# 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:
+ -# Under "Project Admin", use the "File Manager"
+ -# Create a new folder under "openocd" named "${PACKAGE_VERSION}"
+ -# Upload the @c NEWS file and mark it as the release notes.
+ -# Upload the three source archive files, using the Web interface,
+ into that folder. Verify the upload worked OK by checking the
+ MD5 and SHA1 checksums computed by SourceForge against the
+ versions created as part of staging the release.
+ -# Also upload doc/openocd.pdf (the User's Guide) so the version
+ matching each release will be easily available.
+ -# Select each file in the release, and use the property panel
+ to set its type and select the right release notes.
+ - .tar.bz2: Linux, Mac
+ - .tar.gz: BSD, Solaris, Others
+ - .zip: Windows
+ - For openocd.pdf just associate it with the right release notes.
+ -# Create an SF.net project news update.
+ -# Depending on how paranoid you're feeling today, verify the images by
+ downloading them from the websites and making sure there are no
+ differences between the downloaded copies and your originals.
+ -# Publish User's and Developer's Guides to the project web sites:
+ -# Use SCP to update the SF.net web site with PDF and HTML for the
+ User's Guide, and HTML for the developer's guide ... you can
+ instantiate a shell.sourceforge.net instance and set up symlinks
+ from your home directory, to simplify this process.
-# 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.
- -# 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).
+ -# optionally:
+ -# Post an update on the OpenOCD blog.
+ -# Announce updates on freshmeat.net and other trackers.
+ -# Submit updates to news feeds (e.g. Digg, Reddit, etc.).
+-# Resume normal development on mainline, by opening the merge window for
+ the next major or minor release cycle. (You might want to do this
+ before all the release bits are fully published.)
+ - Update the version label in the @c configure.ac file:
+ - Restore @c -dev version tag.
+ - For a new minor release cycle, increment the release's minor number
+ - For a new major release cycle, increment the release's major number
+ and zero its minor number
+ - Archive @c NEWS file as "<code>doc/news/NEWS-${PACKAGE_VERSION}</code>".
+ - Create a new @c NEWS file for the next release
+ - Commit those changes.
+ - Push all the updates to mainline.
+ - Last updates for the release, including the release tag (you
+ will need to "git push --tags").
+ - Updates opening the merge window
+ - At this point, it's OK for commiters to start pushing changes
+ which have been held off until the next release. (Any bugfixes to
+ this release will be against a bug-fix release branch starting from
+ the commit you tagged as this release, not mainline.)
+ - Announce to the openocd-development list. Ideally, you will also
+ be able to say who is managing the next release cycle.
+
+To start a bug-fix release branch:
+-# Create a new branch, starting from a major or
+ minor release tag
+-# Restore @c -dev version tag.
+-# Bump micro version number in configure.ac
+-# Backport bugfix patches from mainline into that branch.
+ (Always be sure mainline has the fix first, so it's hard
+ to just lose a bugfix.)
+-# Commit and push those patches.
+-# When desired, release as above ... except note that the next
+ release of a bugfix branch is never a new major or minor release
+
+@subsection releasescriptcmds Release Script Commands
+
+The @c release.sh script automates some of the steps involved
+in making releases, simplifying the Release Manager's work.
+
+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
+
+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
+
+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 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
+
+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
projects / fw / openocd / blobdiff