Commit first draft of release process documentation.

git-svn-id: svn://svn.berlios.de/openocd/trunk@2453 b42882b7-edfa-0310-969c-e2dbd0fdcd60

2 files changed, 123 insertions, 0 deletions

diff --git a/doc/manual/main.txt b/doc/manual/main.txt
index a6e12d4e..b9430b6d 100644
--- a/doc/manual/main.txt
+++ b/doc/manual/main.txt
@@ -18,6 +18,7 @@ check the mailing list archives to find the status of your feature (or bug).
   follow when submitting patches to the project.
 - The @subpage bugs page contains the content of the BUGS file, which
   provides instructions for submitting bug reports to the maintainers.
+- The @subpage releases page describes the project's release process.
 
 @ref primer provide introductory materials for new developers on various
 specific topics.
diff --git a/doc/manual/release.txt b/doc/manual/release.txt
new file mode 100644
index 00000000..5ce3e11b
--- /dev/null
+++ b/doc/manual/release.txt
@@ -0,0 +1,122 @@
+/** @page releases Release Processes
+
+This page provides an introduction to the OpenOCD Release Proceses:
+- @ref releaseswhy
+- @ref releaseswho
+- @ref releaseswhen
+- @ref releaseshow
+
+@section releaseswhy Why Produce Releases?
+
+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.
+
+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-\<version\>.{tar.gz,tar.bz2,zip} archives, which will be
+suitable for being released when produced properly.
+
+When released for users, these archives present several important
+advantages when contrasted to using the Subversion repository:
+
+-# 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.
+
+Hopefully, this shows several good reasons to produce regular releases,
+but these 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.
+
+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.
+
+@section releaseswho OpenOCD Release Manager
+
+OpenOCD archive releases will be produced by an individual filling the
+role of <i>Release Manager</i>.  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
+-# Upload packages and post announcements of their availability:
+  -# Release packages into files section of berliOS project site.
+  -# 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).
+
+ */
+/** @file
+This file contains the @ref releases page.
+ */