Commit dc342f45 authored by David Brownell's avatar David Brownell
Browse files

Developer's Guide: refresh release procedures



Be a closer match to what I've actually done for the past few cycles.

In particular, hold off pushing repository updates until after the
packages are published, as part of opening the merge window, and
mention the utility commands which actually create the archives.
Signed-off-by: default avatarDavid Brownell <dbrownell@users.sourceforge.net>
parent c8ea748d
...@@ -84,8 +84,8 @@ the minor version will @a also be zero (<code>y = 0, z = 0</code>). ...@@ -84,8 +84,8 @@ the minor version will @a also be zero (<code>y = 0, z = 0</code>).
After these required numeric components, release version strings After these required numeric components, release version strings
may contain tags such as as <em>-rc1</em> or <em>-rc2</em>. may contain tags such as as <em>-rc1</em> or <em>-rc2</em>.
These 'rc' tags indicate "release candidate" versions of the package. These 'rc' tags indicate "release candidate" versions of the package.
Like the major/minor/micro numbers, these tags will be manipulated Like major/minor/micro numbers, these are updated
by the automated release process. as part of the release process.
The release process includes version number manipulations to the tree The release process includes version number manipulations to the tree
being released, ensuring that all numbers are incremented (or rolled being released, ensuring that all numbers are incremented (or rolled
...@@ -277,22 +277,34 @@ support; the Release Manager isn't the only participant. ...@@ -277,22 +277,34 @@ support; the Release Manager isn't the only participant.
The following steps should be followed to produce each release: The following steps should be followed to produce each release:
-# Produce final patches to mainline (or a release branch). Nobody -# Produce final patches using a local clone of mainline. Nobody
except the RM should be committing anything. except the RM should be committing anything. <em>Everyone with commit
-# Finalize @c NEWS file to describe the changes in the release 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 file is used to automatically post "blurbs" about the project.
- This material should be produced during the development cycle. - This material should have been produced during the development cycle,
- Add a new item for each @c NEWS-worthy contribution, when committed. 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) -# Bump library version if our API changed (not yet required)
-# Update and commit the final package version in @c configure.in: -# Update and commit the final package version in @c configure.in:
<code>tools/release/version.sh</code> may help ensure the versions (The <code>tools/release/version.sh</code> script might help ensure
are named consistently: the versions are named properly.):
-# Remove @c -dev tag. -# Remove @c -dev tag.
-# Update the @c -rc tag: -# Update any @c -rc tag:
- If producing the final release from an -rc series, remove it - If producing the final release from an -rc series, remove it
- If producing the first RC in a series, add rc1 - If producing the first RC in a series, add rc1
- If producing the next RC in a series, bump the rc number - If producing the next RC in a series, bump the rc number
-# Commit that version change. -# Commit that version change, with a good descriptive comment.
-# Create a git tag for the final commit, with a tag name matching -# 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> the version string in <code>configure.in</code> (including <em>-rcN</em>
where relevant): where relevant):
...@@ -301,49 +313,92 @@ PACKAGE_VERSION="x.y.z" ...@@ -301,49 +313,92 @@ PACKAGE_VERSION="x.y.z"
PACKAGE_TAG="v${PACKAGE_VERSION}" PACKAGE_TAG="v${PACKAGE_VERSION}"
git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}" git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}"
@endverbatim @endverbatim
-# Prepare to resume normal development on mainline (major or minor release) -# Do not push those changes to mainline yet; only builds using the
- Update the version label source archives you will be creating should ever be labeled as
- Restore @c -dev version tag. official releases (with no "-dev" suffix). Since mainline is a
- For a new minor release cycle, increment the release's minor number development tree, these will be pushed later, as part of opening
- For a new major release cycle, increment the release's major number the merge window for the next release cycle (restoring the "-dev"
and zero its minor number suffix for that next release.) Those version and tag updates are
- Archive @c NEWS file as "<code>doc/news/NEWS-${PACKAGE_VERSION}</code>". the last ones to be included in the release being made.
- Create a new @c NEWS file for the next release -# Produce the release files, using the local clone of the source
- Commit those changes, and push the commit and the release tag tree which holds the release's tag and updated version in
to mainline. @c configure.in ... this is used only to produce the release, and
-# Produce the package source archives: all files should already be properly checked out.
-# <em>Start with a new clone of the source tree</em>, with the -# Run <code>tools/release.sh package</code> to produce the
release's tag. This is used only for producing these packages. source archives. This automatically bootstraps and
-# Checkout the appropriate tag: configures the process.
<code>git checkout "${PACKAGE_VERSION}"</code> -# Run <code>tools/release.sh stage</code> to create an @c archives
-# @c bootstrap, @c configure, and @c make the package. directory with the release data, including MD5 and SHA1
-# Run <code>make distcheck</code> to produce the distribution archives. checksum files (which are used with Berlios).
-# Run <code>make maintainer-clean</code> verify the repository is empty. -# Sanity check at least one of those archives, by extracting and
-# Create signature files using @c md5sum, @c sha1sum, etc. configuring its contents, using them to build a copy of OpenOCD,
-# Publish documentation for the release: and verifying that the result prints the correct release version
- Allow users to access the documentation for each of our releases. in its startup banner. (For example,
- Place static copies of the following files on the project website: "configure --enable-ft2232_libftdi --enable-parport"
- @c NEWS: to provide a blurb for each release then "make" and run "src/openocd -v" as a sanity check.)
- User's Guide, Developer Manual: to allow easy on-line viewing -# Run <code>make docs</code> to create the
documentation which will be published.
-# Upload packages and post announcements of their availability: -# Upload packages and post announcements of their availability:
-# Release packages into files section of project sites: -# Release packages into files section of project sites:
- SF.net: - SF.net:
-# Create a new folder named "${PACKAGE_VERSION}" -# Under "Project Admin", use the "File Manager"
-# Select new folder as the target for uploads. -# Create a new folder under "openocd" named "${PACKAGE_VERSION}"
-# Upload files via Web interface into new -# Upload the @c NEWS file and mark it as the release notes.
-# Set platform types for each archive: -# 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.bz2: Linux, Mac
- .tar.gz: BSD, Solaris, Others - .tar.gz: BSD, Solaris, Others
- .zip: Windows - .zip: Windows
- For openocd.pdf just associate it with the right release notes.
-# Create an SF.net project news update.
- Berlios: - Berlios:
-# Create the new release for the new version.
-# Provide @c NEWS file, as requested. -# Provide @c NEWS file, as requested.
-# Upload files via FTP to ftp://ftp.berlios.de/incoming/ -# Upload the release files via FTP to ftp://ftp.berlios.de/incoming/
-# Edit descriptions for each file. -# Edit descriptions for each file (one at a time) Note that Berlios
does not automatically checksum files, and it uses a very old
version of the SourceForge code with user interface issues.
-# Click button to send E-mail Release Notice. -# Click button to send E-mail Release Notice.
-# 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.
-# (How to update the Berlios web site with the same data?)
-# Post announcement e-mail to the openocd-development list. -# Post announcement e-mail to the openocd-development list.
-# Announce updates on freshmeat.net and other trackers. -# optionally:
-# Submit big updates to news feeds (e.g. Digg, Reddit, etc.). -# Post an update on the Berlios blog (if it lets you)
-# 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: To start a bug-fix release branch:
-# Create a new branch, starting from a major or -# Create a new branch, starting from a major or
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment