/** @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 releases periodically for many reasons. This section provides the key reasons for making releases on a regular basis and why a set of release processes should be used to produce them. At any time, source archives can be produced by running make dist in the OpenOCD project tree. With the 0.2.0 release, this command will package the tree into several popular archive formats: openocd-\.{tar.gz,tar.bz2,zip}. If produced properly, these files are suitable for release to the public. 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 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 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 openocd -v invocation displays it; as does the Tcl version command. Labels for released versions look like 0.3.0, or 0.3.0-rc1 for a preliminary release. Non-released (developer) versions look like 0.3.0-dev, or 0.3.0-rc1-dev. In all cases, additional tags may be appended to those base release version labels. The tools/release/version.sh 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 bug-fix release, the micro version number will be non-zero (z > 0). For a minor release, the micro version number will be zero (z = 0). For a major releases, the minor version will @a also be zero (y = 0, z = 0). After these required numeric components, release version strings may contain tags such as as -rc1 or -rc2. These 'rc' tags indicate "release candidate" versions of the package. Like the major/minor/micro numbers, these tags will be manipulated by the automated 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.in script of a local copy of the source tree, giving a version label like 0.3.0-foo: @code tools/release/version.sh version tag add 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. 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. @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 -dev 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 snapshot 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 dirty tag). This information can be useful when tracking down bugs. (Note that at this writing, the tags do not directly correspond to git describe output. The hash ID can be used with git show, but the preceding segments can't.) @section releasewho Release Manager OpenOCD archive releases will be produced by an individual filling the role of Release Manager, hereafter abbreviated as RM. 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. - ... several weeks of merge window ... - 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 - ... more RC milestones, until ready ... - 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 to mainline (or a release branch). Nobody except the RM should be committing anything. -# 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) -# Update and commit the final package version in @c configure.in: tools/release/version.sh may help ensure the versions are named consistently: -# Remove @c -dev tag. -# Update the @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. -# Create a git tag for the final commit, with a tag name matching the version string in configure.in: @verbatim 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 on mainline: - Restore @c -dev version tag. - To start a new major (or minor) release cycle on the @c master branch: - Archive @c NEWS file as "doc/news/NEWS-${PACKAGE_VERSION}". - Create a new @c NEWS file for the next release - Commit those changes, and push the commit and the release tag to mainline. -# Produce the package source archives: -# Start with a new clone of the source tree, with the release's tag. This is used only for producing these packages. -# Checkout the appropriate tag: git checkout "${PACKAGE_VERSION}" -# Produce a ChangeLog for the release (using @c git2cl). -# @c bootstrap, @c configure, and @c make the package. -# Run make distcheck to produce the distribution archives. -# Run make maintainer-clean 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 NEWS: to provide a blurb for each release - @c ChangeLog: to show exactly what has been changed - User's Guide, Developer Manual: to allow easy on-line viewing -# Upload packages and post announcements of their availability: -# 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. -# 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.). 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.in -# 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 This file contains the @ref releases page. */