|
- /** @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 releasescriptcmds - 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 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 <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 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 <em>0.3.0-foo</em>:
-
- @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 <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>, 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 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:
- <code>tools/release/version.sh</code> 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 <code>configure.in</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
- -# Prepare to resume normal development on mainline (major or minor release)
- - Update the version label
- - 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, and push the commit and the release tag
- to mainline.
- -# Produce the package source archives:
- -# <em>Start with a new clone of the source tree</em>, with the
- release's tag. This is used only for producing these packages.
- -# Checkout the appropriate tag:
- <code>git checkout "${PACKAGE_VERSION}"</code>
- -# @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 NEWS: to provide a blurb for each release
- - 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 file, 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.
- */
|