From e8dc384be9d4bf2b7ed61178c02154dffdb15a9e Mon Sep 17 00:00:00 2001 From: Zachary T Welch Date: Tue, 20 Oct 2009 17:11:33 -0700 Subject: Rewrite release script to use GIT. Update documentation to reflect GIT methodology. Rewrite release.sh script to use appropriate process. With this update, tools/release.sh can be used for producing private release tags on local branches. The documentation still needs work, but their use for v0.3.x should help rectify the deficiences. --- doc/manual/release.txt | 198 ++++++------------- tools/release.sh | 524 ++++++++++++++----------------------------------- 2 files changed, 210 insertions(+), 512 deletions(-) diff --git a/doc/manual/release.txt b/doc/manual/release.txt index 64dcb811..00e987e4 100644 --- a/doc/manual/release.txt +++ b/doc/manual/release.txt @@ -212,46 +212,47 @@ Even with the release script, some steps require clear user intervention The following steps should be followed to produce each release: --# Produce final patches to mainline (or release branch): +-# Produce final manual patches to mainline (or release branch): -# 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 -dev tag from package version in configure.in: - - For major/minor releases, remove version tag from mainline, @a or - - For bug-fix releases, remove version tag from release branch. --# Branch or tag the required tree in the git repository: - - Tags and branches for releases must be named consistently: @par - "${PACKAGE_TARNAME}-${PACKAGE_VERSION}" - - For a major/minor release from the mainline, the code should be - tagged in the repository: + -# Bump library version if our API changed (not yet required) +-# Produce and tag the final revision in the git repository: + - Update and commit the final package version in @c configure.in : + -# Remove @c -dev tag. + -# Remove @c -rc tag, if producing the final release from an -rc series. + - Tags must be named consistently: @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: + - Tag the final commit with a consistent GIT tag name and message: @verbatim -svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG} +PACKAGE_VERSION="x.y.z" +PACKAGE_TAG="v${PACKAGE_VERSION}" +git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}" @endverbatim --# Prepare to resume normal development 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 mainline: - -# Bump major or minor package version in mainline. - -# Restore version tag to mainline. - - For bug-fix releases from a release branch: - -# Bump bug-fix version in release branch. - -# Restore version tag to release branch. +-# Prepare to resume normal development on the branch: + - Restore @c -dev and -@c -rc0 version tags. + - To start a new major (or minor) release cycle on the @c master branch: + - Bump major (or minor) package version, zeroing sub-components. + - Add -rc0 version tag: + - This insures casual releases from GIT always increase monotonically. + - For example, a major increment after releasing 1.2.3 starts 2.0.0-rc0-dev. + - Archive @c NEWS file as "doc/news/NEWS-${PACKAGE_VERSION}". + - Create a new @c NEWS file for the next release + - To start a bug-fix release on a non-master branch: + -# Bump bug-fix version. + - To start another release candidate on a major or minor branch: + -# Bump rc tag. -# 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). + -# Checkout the appropriate tag: +git checkout $(git tag ) "${PACKAGE_VERSION}" + -# Produce a ChangeLog for the release (using @c git2cl). -# @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. + -# Create signature files using @c md5sum, @c sha1sum, etc. -# Publish documentation for the release: - Allow users to access the documentation for each of our releases. - Place static copies of the following files on the project website: @@ -259,12 +260,21 @@ svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG} - @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 project sites: + - SF.net: + -# Create a new folder named "${PACKAGE_VERSION}" + -# Select new folder as the target for uploads. + -# Upload files via Web interface into new + -# Set platform types for each archive: + - .tar.bz2: Linux, Mac + - .tar.gz: BSD, Solaris, Others + - .zip: Windows + - Berlios: -# Create the new release for the new version. -# Provide @c NEWS 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 + -# Click button to send E-mail Release Notice. -# Post announcement e-mail to the openocd-development list. -# Announce updates on freshmeat.net and other trackers. -# Submit big updates to news feeds (e.g. Digg, Reddit, etc.). @@ -275,7 +285,7 @@ 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, +Presently, the @c release.sh script automates steps 2 through 4, allowing the Release Manager from perform these tasks in easy steps. The following task still need to be automated: @@ -285,61 +295,34 @@ The following task still need to be automated: - 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 project mainline. - 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 +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 -Run tools/release.sh help for current command support. +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: -- @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 git repository that -cannot be undone. +- 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 @@ -351,66 +334,9 @@ affect its behavior: @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) mainline from the 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 +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 diff --git a/tools/release.sh b/tools/release.sh index f1ed4a73..26be1511 100755 --- a/tools/release.sh +++ b/tools/release.sh @@ -7,142 +7,27 @@ #CONFIG_OPTS="" #MAKE_OPTS="" -## DO NOT PERFORM LIVE RELEASES UNLESS YOU ARE THE RELEASE MANAGER!!! -RELEASE_DRY_RUN=1 -## set this to perform individual steps on past releases -RELEASE_VERSION= - -die() { - echo "$@" >&2 - exit 1 -} - -svn_info_get() { - svn info | grep "$1" | cut -d':' -f2- | cut -c2- -} - -svn_setup_load() { - SVN_ROOT="$(svn_info_get 'Repository Root')" - SVN_URL="$(svn_info_get 'URL')" - - SVN_TRUNK="${SVN_ROOT}/trunk" - - SVN_BRANCHES="${SVN_ROOT}/branches" - PACKAGE_BRANCH="${SVN_BRANCHES}/${PACKAGE_RELEASE}" - - SVN_TAGS="${SVN_ROOT}/tags" - PACKAGE_TAG="${SVN_TAGS}/${PACKAGE_RELEASE}" - - if [ "${SVN_URL}" = "${SVN_TRUNK}" ]; then - RELEASE_TYPE=minor - elif [ "${SVN_URL/${SVN_BRANCHES}/}" != "${SVN_URL}" ]; then - RELEASE_TYPE=micro - else - echo "error: bad URL: ${SVN_URL}" >&2 - die "unable to branch from the current location" - fi -} -svn_setup_show() { - cat < +usage: $0 ... +Command Options: + --next name The branch's next release type: major, minor, micro, rc, tag. + --next-tag name The name for the package version tag. + --live Perform the actions in the repository. 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. @@ -150,42 +35,26 @@ Build Commands: build Compiles the project; runs configure, if needed. Packaging Commands: - changelog Generate a new ChangeLog using svn2cl. + changelog Generate a new ChangeLog using ${SCM}2cl. 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. - maryslamb Mary had a little lamb, but no one noticed. 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. USAGE exit 0 } do_usage() { usage; } do_help() { usage; } -do_info_show() { +do_info() { echo "Current Release Analysis:" package_info_show - svn_setup_show -} - -do_info() { - package_info_load - svn_setup_load - do_info_show } do_bootstrap() { @@ -213,26 +82,16 @@ maybe_build() { [ -f "src/openocd" ] || do_build; } do_build_clean() { [ -f Makefile ] && make maintainer-clean >/dev/null; } do_changelog() { - echo "Updating working copy to HEAD..." - do_svn update echo "Creating ChangeLog..." - svn2cl -i --authors AUTHORS.ChangeLog -} -maybe_changelog() { - if [ -z "${RELEASE_DRY_RUN}" ] \ - || [ ! -f ChangeLog ] \ - || [ "$(cat ChangeLog | wc -l)" -lt 2 ] - then - do_changelog - fi + local CMD=tools/git2cl/git2cl + eval ${CMD} ${OPTS} > ChangeLog } do_changelog_clean() { - do_svn revert ChangeLog + git checkout ChangeLog } do_package() { - package_info_load - maybe_changelog + do_changelog maybe_build echo "Building distribution packages..." make ${MAKE_OPTS} distcheck 2>&1 | perl tools/logger.pl > "release-pkg.log" @@ -266,207 +125,76 @@ do_stage_clean() { rm -v -f -r archives; } do_clean() { do_build_clean do_package_clean - rm -v -f configure - - svn revert configure.in + do_changelog_clean rm -v -f release-*.log } do_clean_all() { do_clean - do_changelog_clean do_stage_clean } -do_version_usage() { - cat << USAGE -usage: $0 version -Version Commands: - tag {add|remove}