X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fmanual%2Frelease.txt;h=44de4464f5c059e368da283b9ab3dfa1c5d24582;hp=056628e8faa3d25beb2a863983aa54d301310610;hb=1c6f7075f75db1e4da3b918a8c64f2b178712942;hpb=dc342f45f6c8ec02431495863687b3638f1646d5 diff --git a/doc/manual/release.txt b/doc/manual/release.txt index 056628e8fa..44de4464f5 100644 --- a/doc/manual/release.txt +++ b/doc/manual/release.txt @@ -36,7 +36,7 @@ several important advantages compared to using the source repository 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, + involves spending some time specifically on quality improvements, including bugfixing source code and documentation. -# They provide developers with the flexibility needed to address larger issues, which sometimes involves temporary breakage. @@ -107,14 +107,14 @@ original code base. Each packager release should have a unique version. For example, the following command will add a 'foo' tag to the -configure.in script of a local copy of the source tree, giving +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 version tag add foo +tools/release/version.sh tag add foo @endcode -This command will modify the configure.in script in your working copy +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 @@ -125,7 +125,7 @@ each time a derived package is released, incrementing the tag's version to facilitate tracking the changes you have distributed. @code -tools/release/version.sh version bump tag foo +tools/release/version.sh bump tag foo @endcode Of course, any patches in your branches must be provided to @@ -149,7 +149,7 @@ specific git revisions: 0.3.0-rc1-dev-00015-gf37c9b8-dirty -indicates a development tree based on git revison f37c9b8 +indicates a development tree based on git revision 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. @@ -296,7 +296,7 @@ The following steps should be followed to produce each release: 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.in: + -# 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. @@ -306,7 +306,7 @@ The following steps should be followed to produce each release: - 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.in (including -rcN + the version string in configure.ac (including -rcN where relevant): @verbatim PACKAGE_VERSION="x.y.z" @@ -322,19 +322,19 @@ git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}" 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.in ... this is used only to produce the release, and + @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 (which are used with Berlios). + 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" + "configure --enable-parport" then "make" and run "src/openocd -v" as a sanity check.) -# Run make docs to create the documentation which will be published. @@ -357,13 +357,6 @@ git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}" - .zip: Windows - For openocd.pdf just associate it with the right release notes. -# Create an SF.net project news update. - - Berlios: - -# Provide @c NEWS file, as requested. - -# Upload the release files via FTP to ftp://ftp.berlios.de/incoming/ - -# 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. -# 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. @@ -372,16 +365,15 @@ git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}" 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. -# optionally: - -# Post an update on the Berlios blog (if it lets you) + -# 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.in file: + - 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 @@ -393,7 +385,7 @@ git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}" - 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 + - At this point, it's OK for committers 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.) @@ -404,7 +396,7 @@ 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.in +-# 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.) @@ -431,7 +423,7 @@ tools/release.sh --type=micro branch 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. +proceeding with a live release. @subsection releasescriptopts Release Script Options