-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.