summaryrefslogtreecommitdiff
path: root/doc/manual
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual')
-rw-r--r--doc/manual/main.txt1
-rw-r--r--doc/manual/release.txt122
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.
+ */