doc/manual/release.txt

   1 /** @page releases Release Processes
   2
   3 This page provides an introduction to the OpenOCD Release Proceses:
   4 - @ref releaseswhy
   5 - @ref releaseswho
   6 - @ref releaseswhen
   7 - @ref releaseshow
   8
   9 @section releaseswhy Why Produce Releases?
  10
  11 The OpenOCD maintainers should produce releases periodically.
  12 he reasons for several reasons that should be given in detail, before
  13 explaining who and how the processes occur.
  14
  15 At any time, a "source archives" can be produced by running 'make dist'
  16 in the OpenOCD project tree.  With the 0.2.0 release, this command will
  17 produce openocd-\<version\>.{tar.gz,tar.bz2,zip} archives, which will be
  18 suitable for being released when produced properly.
  19
  20 When released for users, these archives present several important
  21 advantages when contrasted to using the Subversion repository:
  22
  23 -# They allow others to package and distribute the code to users.
  24 -# They build easier for developers, because they contain
  25    a working configure script that was produced by the Release Manager.
  26 -# They prevent users from trying a random HEAD revision of the trunk.
  27 -# They free developers from answering questions about trunk breakage.
  28
  29 Hopefully, this shows several good reasons to produce regular releases,
  30 but these release processes were developed with some additional design
  31 goals in mind.  Specifically, the releases processes should have the
  32 following properties:
  33
  34 -# Produce successive sets of release archives cleanly and consistently.
  35   - Implementable as a script that automates the critical release steps.
  36 -# Prevent human operators from doing it wrong, as much as possible.
  37 -# Allow scheduling and automation of release process milestones.
  38
  39 The current release processes are documented in the following sections.
  40 They attempt to meet these design goals, but there are many improvements
  41 remaining to be made toward automating the process.
  42
  43 @section releaseswho OpenOCD Release Manager
  44
  45 OpenOCD archive releases will be produced by an individual filling the
  46 role of <i>Release Manager</i>.  This individual determines the schdule
  47 (@see releaseswhen) and executes the release processes for the
  48 community.  Each release requires one individual to fulfill this role,
  49 and these processes should survive any such transition gracefully.
  50
  51 @section releaseswhen OpenOCD Release Schedule
  52
  53 The OpenOCD release process must be carried out on a periodic basis
  54 in order to realize the benefits outlined above (@see releaseswhy).
  55
  56 Starting with the 0.2.0 release, the OpenOCD project should produce a
  57 new minor release each month, with a major release once per year.  Bug
  58 fix releases could be provided more frequently; however, these should
  59 not be a priority for the Release Manager until the processes have been
  60 fully automated, to use resources most efficiently.
  61
  62 If T is the time of the next release, then the following milestones
  63 describe the release milestones for each new release cycle.
  64
  65 - T minus one month: start of new development cycle
  66 - T minus two weeks: announce pending trunk closure to new work
  67 - T minus one week: close trunk to new work, begin testing phase
  68 - T minus two days: call for final bug fixes
  69 - T minus one day: produce -rc packages and distribute to testers
  70 - T minus one hour: produce final packages and post on-line
  71
  72 The process of scheduling release milestones should be community driven,
  73 though the Release Manager should attempt to follow these guidelines.
  74 Specifically, missing features that were scheduled for a release should
  75 be dropped, rather than delaying the release cycle to wait for them.
  76
  77 @section releaseshow Release Process: Step-by-Step
  78
  79 The exact process likely requires a few releases to work out the bugs,
  80 as it will take some experience before a script can be developed and
  81 tested that does everything safely and robustly.  Even then, some steps
  82 require clear user intervention -- and not only by the release manager.
  83
  84 -# Produce final patches to the trunk (or release branch):
  85   - add NEWS item to describe the release changes? (not ready for 0.2.0)
  86     - the community should try to help produce this material
  87     - can be used to automatically post "blurbs" about the project.
  88   - bump library version if our API changed (not yet required)
  89   - bump package version
  90 -# Produce and verify the binary packages:
  91   -# Start with a clean working copy, used for producing releases only.
  92   -# produce a ChangeLog for the release (using svn2cl).
  93   -# bootstrap, configure, and build the package.
  94   -# run 'make distcheck' to produce the distribution archives.
  95   -# run 'make maintainer-clean'; verify the repository is empty again.
  96 -# Branch or tag the required tree in the Subversion repository:
  97   - For a major/minor release from the main trunk, branch and tag it:
  98     -# svn cp .../trunk .../branches/${BRANCH_VERSION}
  99     -# svn cp .../branches/${BRANCH_VERSION} .../tags/${PACKAGE_VERSION}
 100   - For a bug-fix or final release from a release branch, only tag it:
 101     -# svn cp .../branches/${BRANCH_VERSION} .../tags/${PACKAGE_VERSION}
 102   - where:
 103     - BRANCH_VERSION - is x.0.0-trunk or x.y.0-trunk
 104     - PACKAGE_VERSION - is x.y.z
 105 -# Upload packages and post announcements of their availability:
 106   -# Release packages into files section of berliOS project site.
 107   -# Post announcement e-mail to the openocd-development list.
 108 -# After the community has checked their sanity, we can post "blurbs":
 109   -# Post NEWS update to freshmeat.net and other trackers.
 110   -# Submit big NEWS updates to news feeds (e.g. Digg, Reddit, etc.).
 111
 112 Totally-automated packaging and distribution of OpenOCD requires more
 113 patching (post-0.2.0), but the final script(s) should be able to manage
 114 most steps in these processes.  The steps requiring user input can be
 115 guided by an "assistant" that walks the Release Manager through the
 116 process from beginning to end, performing basic sanity checks on their
 117 various inputs (e.g. the NEWS blurb).
 118
 119  */
 120 /** @file
 121 This file contains the @ref releases page.
 122  */