From 153270fea3eb06092f2947e5c8c491e6bbffcccd Mon Sep 17 00:00:00 2001 From: zwelch Date: Sat, 4 Jul 2009 03:47:54 +0000 Subject: [PATCH] Major update to release process documentation: - Provide overview of OpenOCD versioning schema. - Outline responsibilities and authority of the release manager. - Explain the need for flexibility in the release schedule. - Add and refine the release process steps. - Include tutorials for using new release script. - Many more improvements, too numerous to list. git-svn-id: svn://svn.berlios.de/openocd/trunk@2462 b42882b7-edfa-0310-969c-e2dbd0fdcd60 --- doc/manual/release.txt | 375 +++++++++++++++++++++++++++++++++++------ 1 file changed, 319 insertions(+), 56 deletions(-) diff --git a/doc/manual/release.txt b/doc/manual/release.txt index 5ce3e11b9e..45652c2eee 100644 --- a/doc/manual/release.txt +++ b/doc/manual/release.txt @@ -1,21 +1,29 @@ /** @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 releasescript - 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? + +The OpenOCD maintainers should produce releases periodically. This +section gives several reasons to explain the reasons for making releases +on a regular basis. These reasons lead to motivation for developing and +following a set of release processes. The actual processes are +described in the remainder of the @ref releases sections. 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-\.{tar.gz,tar.bz2,zip} archives, which will be -suitable for being released when produced properly. +produce openocd-\.{tar.gz,tar.bz2,zip} archives. These files +will be suitable for being released when produced properly. When released for users, these archives present several important advantages when contrasted to using the Subversion repository: @@ -32,35 +40,100 @@ 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. +-# Implementable as a script that automates the critical release steps. +-# Prevent human operators from producing bad releases, when possible. -# Allow scheduling and automation of release process milestones. The current release processes are documented in the following sections. -They attempt to meet these design goals, but there are many improvements +They attempt to meet these design goals, but there may improvements remaining to be made toward automating the process. -@section releaseswho OpenOCD Release Manager +@section releaseversions Release Versions + +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 a 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). + +The trunk and all branches should have the tag '-in-development' in +their version number. This tag helps developers identify reports +created from the Subversion repository, 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. + +@subsection releaseversionsdist Patched Versions + +Distributors of patched versions of OpenOCD are encouraged to extend +the version string when producing external releases, as this helps to +identify your particular distribution series. + +@subsection releaseversionsdist Version Processes + +The release process includes version number manipulations to the tree +being released, ensuring that all numbers are incremented at the right +time and in the proper locations of the repository. + +The version numbers for any branch should monotonically +increase to the next successive integer, except when reset to zero +during major or minor releases. The community should decide when +major and minor milestones will be released. + +@section releasewho Release Manager OpenOCD archive releases will be produced by an individual filling the -role of Release Manager. 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. +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. -@section releaseswhen OpenOCD Release Schedule +@subsection releasewhowhat RM Responsibilities -The OpenOCD release process must be carried out on a periodic basis -in order to realize the benefits outlined above (@see releaseswhy). +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. + +@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 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. +new minor release every month or two, with a major release once a year. +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. -If T is the time of the next release, then the following milestones -describe the release milestones for each new release cycle. +@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 T is the time of the next release, then the following schedule +might describe some of the key milestones of the new release cycle: - T minus one month: start of new development cycle - T minus two weeks: announce pending trunk closure to new work @@ -68,25 +141,62 @@ describe the release milestones for each new release cycle. - 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 +- T minus zero: Announce the release to our mailing list and the world. + +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. + +@note The OpenOCD project does not presently produce -rc packages. As +such, the step suggested in the list above should be read as trying to +stimulate others to test the project build and packaging on as many +platforms as possible. This proposition will be palatable once release +management tools have been committed to the tree. + +@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. By the end, missing features that were +scheduled for a release must be dropped by the Release Manager, rather +than allowing the release cycle to be delayed while waiting for them. -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. +Despite any assurances this schedule may appear to give, the Release +Manager cannot schedule the work that will be done on the project, +when it will be submitted, review, and deemed suitable to be committed. +In this way, 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 churn. -@section releaseshow Release Process: Step-by-Step +In particular, the suggested period of "one or two month" reflects some +expectation of a fairly high rate of development. 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 . -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. +@section releasehow Release Process: Step-by-Step + +The release process may require a few iterations to work out any bugs. +Even with the release script, some steps require clear user intervention +-- and not only by the Release Manager. + +The following steps should be followed to produce each release: -# Produce final patches to the trunk (or release branch): - - add NEWS item to describe the release changes? (not ready for 0.2.0) + -# 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 + -# bump library version if our API changed (not yet required) + -# Remove -in-development tag from package version: + - For major/minor releases, remove version tag from trunk. + - For bug-fix releases, remove version tag from release branch. -# 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). @@ -94,27 +204,180 @@ require clear user intervention -- and not only by the release manager. -# 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 + - Tags and branches for releases must be named consistently: @par + "${PACKAGE_TARNAME}-${PACKAGE_VERSION}" + - For a major/minor release from the main trunk, the code should be + branched and tagged in the repository: +@verbatim +svn cp .../trunk .../branches/${RELEASE_BRANCH} +svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG} +@endverbatim + - For bug-fix releases produced in their respective branch, a tag + should be created in the repository: +@verbatim +svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG} +@endverbatim +-# Prepare to resume normal development activities: + - For major/minor release from the trunk: + -# Bump major or minor package version in trunk. + -# Restore version tag to trunk and release branch. + - For bug-fix releases from a release branch: + -# Bump bug-fix version in release branch. + -# Restore version tag to release branch. +-# 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: + - NEWS: to provide a blurb for each release (not yet used) + - ChangeLog: to show exactly what has been changed + - User Guide, Developer Manual: to allow easy on-line viewing -# Upload packages and post announcements of their availability: -# Release packages into files section of berliOS project site. -# 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. + -# Announce updates on 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). +@section releasescript The Release Script + +Many of the processes described in the last section are no longer +entrusted to humans. Instead, the @c release.sh script provides +automation of the mechanical steps. + +Presently, the @c release.sh script automates steps 1(c) through 4, +allowing the Release Manager from perform these tasks in easy steps. + +The following task still need to be automated: + +- Step 5: produce documentation for website using released source archive. +- Step 6(a): package archive upload process. +- Step 6(b): package announcement e-mail process. +- Step 6(c): post files and announce them using releaseforge. + +In addition, support for '-rc' releases needs to be added. + +@subsection releasescriptcmds Release Script Commands + +The following output was taken from the release script: +@verbatim +usage: tools/release.sh + +Main Commands: + info Show a summary of the next pending release. + release Release the current tree as an archive. + upload Upload archives to berliOS project site + +Build Commands: + bootstrap Prepare the working copy for configuration and building. + configure Configures the package; runs bootstrap, if needed. + build Compiles the project; runs configure, if needed. + +Packaging Commands: + changelog Generate a new ChangeLog using svn2cl. + package Produce new distributable source archives. + stage Move archives to staging area for upload. + +Repository Commands: + commit Perform branch and tag, as appropriate for the version. + branch Create a release branch from the project trunk. + tag Create a tag for the current release branch. + +Other Commands: + version ... Perform version number and tag manipulations. + clean Forces regeneration of results. + clean_all Removes all traces of the release process. + help Provides this list of commands. + +For more information about this script, see the Release Processes page +in the OpenOCD Developer's Manual (doc/manual/release.txt). + +WARNING: This script should be used by the Release Manager ONLY. +@endverbatim + +Run tools/release.sh help for current command support. + +@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. +- @c RELEASE_DRY_RUN : Set this to null to perform the live release. + Unless this variable has been (un)set, the release commands will not + affect the repository. + +Proper option handling should be added to set these variables in script. + +@section releasetutorial Release Tutorials + +This section provides tutorials for using the Release Script to perform +common release tasks. + +@subsection releasetutorialminor Minor Release Tutorial + +The tutorials in this section assume the following environment +variables have been set properly: +@verbatim +SVN_USER="maintainer" +SVN_URL="https://${SVN_USER}@svn.berlios.de/svnroot/repos/openocd" +@endverbatim + +@subsection releasetutorialminor Minor Release Tutorial + +This section provides a step-by-step tutorial for a Release Manager to +use to run the @c release.sh script to produce a minor release. + +If the proper environment has been set, the following steps will produce +a new minor release: + +-# Check out (or update) the project trunk from the berliOS repository: +@code +svn checkout "${SVN_URL}/trunk" openocd-trunk +@endcode +-# Change to the new working copy directory: +@code +cd openocd-trunk +@endcode +-# Run @c release.sh to produce the minor release: +@code +tools/release.sh all +@endcode + +@subsection releasetutorialmicro Bug-Fix Release Tutorial + +This section provides a step-by-step tutorial for a Release Manager to +use to run the @c release.sh script to produce a bug-fix release. + +In addition to the environment variables described in the introduction +to these tutorials, the following variables are also used in the +instructions for this section: +@verbatim +PACKAGE_BRANCH_VERSION="x.y.z" +PACKAGE_BRANCH="openocd-${PACKAGE_BRANCH_VERSION}" +@endverbatim + +If the proper environment has been set, the following steps will produce +a new bug-fix release: + +-# Check out (or update) the release branch from the project repository: +@code +svn checkout "${SVN_URL}/branches/${PACKAGE_BRANCH}" "${PACKAGE_BRANCH}" +@endcode +@code +cd "${PACKAGE_BRANCH}" +@endcode +-# Run @c release.sh to produce the bug-fix release: +@code +tools/release.sh all +@endcode + +@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 NEWS blurb). */ /** @file -- 2.30.2