X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fmanual%2Frelease.txt;h=c47796607f51df32c830f00a8f705aa537b35e42;hb=0da2f750a1d437b50b21ac7ee766188a47b37fad;hp=5ce3e11b9ea0ee9496aa510bea7d7ee97f3e474b;hpb=fc240afcac4de15e5d4c0727c0e062ce4d9bbe64;p=openocd diff --git a/doc/manual/release.txt b/doc/manual/release.txt index 5ce3e11b..c4779660 100644 --- a/doc/manual/release.txt +++ b/doc/manual/release.txt @@ -1,66 +1,162 @@ /** @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? -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. +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 released for users, these archives present several important -advantages when contrasted to using the Subversion repository: +advantages when contrasted to using the Subversion repository trunk: --# They allow others to package and distribute the code to users. +-# They allow others to package and distribute the code. -# They build easier for developers, because they contain a working configure script that was produced by the Release Manager. -# They prevent users from trying a random HEAD revision of the trunk. -# They free developers from answering questions about trunk breakage. Hopefully, this shows several good reasons to produce regular releases, -but these release processes were developed with some additional design +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 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. --# Allow scheduling and automation of release process milestones. +-# 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 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). + +@subsection releaseversiontags Version Tags + +After these required numeric components, the version string may contain +one or more version tags, such as '-rc1' or '-in-development'. + +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. + +The 'rc' tags indicate a "release candidate" version of the package. +This tag will also be manipulated by the automated release process. + +Additional tags may be used as necessary. + +@subsection 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. + +For example, the following command will add a 'foo1' tag to the +configure.in script of a local copy of the source tree: + +@code +tools/release.sh version bump tag 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. The same command can be +used each time the derived package is released, incrementing the tag's +version to facilitate tracking the changes you have distributed. + +@subsection releaseversionhow 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 increase monotonically +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 -@section releaseswhen OpenOCD Release Schedule +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. -The OpenOCD release process must be carried out on a periodic basis -in order to realize the benefits outlined above (@see releaseswhy). +@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. + +@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. + +@subsection releasewhenexample Sample Schedule -If T is the time of the next release, then the following milestones -describe the release milestones for each new release cycle. +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,53 +164,262 @@ 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. -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. +@subsection releasewhenflex Schedule Flexibility -@section releaseshow Release Process: Step-by-Step +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 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. +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, reviewed, 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. + +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. + +@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) - - 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. + -# 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) + -# Remove -in-development tag from package version: + - For major/minor releases, remove version tag from trunk, @a or + - For bug-fix releases, remove version tag from release branch. -# 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: + - Archive @c NEWS file as doc/news/NEWS-${PACKAGE_VERSION}. + - Create a new @c NEWS file for the next release + - 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. +-# Produce the package source archives: + -# Start with a clean working copy, used for producing releases only. + -# Switch to release tag branch: svn switch .../${RELEASE_TAG} + -# Produce a ChangeLog for the release (using svn2cl). + -# @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 md5sum, 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 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. + -# Release packages into files section of berliOS project site: + -# 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. + -# Send E-mail Release Notice -# 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. - -# 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). + -# Announce updates on freshmeat.net and other trackers. + -# Submit big updates to news feeds (e.g. Digg, Reddit, etc.). + +@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 [options] + +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 releasescriptopts Release Script Options + +The @c release.sh script recognizes some command-line options that +affect its behavior: + +- @c --live : Use this option to perform a live release. + When this option has been given, the release commands will affect + the repository; otherwise, the script reports the actions to take, + and it produces archives that are unsuitable for public release. + +@note Only the Release Manager should use the @c --live option, as +it will make permanent changes to the Subversion repository that +cannot be undone. + +@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 provides tutorials for using the Release Script to perform +common release tasks. + +@subsection releasetutorialsetup Release Tutorial Setup + +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 @c NEWS blurb). */ /** @file