|
- /** @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 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.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 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.in:
- (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.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
- -# 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.in ... 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 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.
- -# 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.in 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.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.
- */
|