X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fmanual%2Frelease.txt;h=d1447569204b217380f6432fb79c7e14845500da;hp=5ce3e11b9ea0ee9496aa510bea7d7ee97f3e474b;hb=90142e3edb55f03134b4ff2a96fb2dd041dbdf17;hpb=fc240afcac4de15e5d4c0727c0e062ce4d9bbe64 diff --git a/doc/manual/release.txt b/doc/manual/release.txt index 5ce3e11b9e..d144756920 100644 --- a/doc/manual/release.txt +++ b/doc/manual/release.txt @@ -1,120 +1,463 @@ /** @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 releasescriptcmds - 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. -When released for users, these archives present several important -advantages when contrasted to using the Subversion repository: +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. --# They allow others to package and distribute the code to users. --# 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. +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 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 -remaining to be made toward automating the process. +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 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.ac script of a local copy of the source tree, giving +a version label like 0.3.0-foo: + +@code +tools/release/version.sh tag add foo +@endcode + +This command will modify the configure.ac 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. -@section releaseswho OpenOCD Release Manager +@code +tools/release/version.sh 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 relevant repository tag isn't 0.3.0-rc1-dev; +this might change in the future.) + +@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. - -@section releaseswhen OpenOCD Release Schedule - -The OpenOCD release process must be carried out on a periodic basis -in order to realize the benefits outlined above (@see releaseswhy). - -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. - -If T is the time of the next release, then the following milestones -describe the release milestones for each new release cycle. - -- T minus one month: start of new development cycle -- T minus two weeks: announce pending trunk closure to new work -- T minus one week: close trunk to new work, begin testing phase -- 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 - -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. - -@section releaseshow Release Process: Step-by-Step - -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. - --# 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. --# 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 +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 using a local clone of mainline. Nobody + except the RM should be committing anything. Everyone with commit + privileges needs to know and agree to this in advance! 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.ac: + (The tools/release/version.sh 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 configure.ac (including -rcN + 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.ac ... this is used only to produce the release, and + all files should already be properly checked out. + -# Run tools/release.sh package to produce the + source archives. This automatically bootstraps and + configures the process. + -# Run tools/release.sh stage 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 make docs to create the + documentation which will be published. -# Upload packages and post announcements of their availability: - -# Release packages into files section of berliOS project site. + -# 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. --# 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). + -# 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.ac 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 "doc/news/NEWS-${PACKAGE_VERSION}". + - 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.ac +-# 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