You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

404 lines
17 KiB

  1. /** @page releases Release Processes
  2. This page provides an introduction to the OpenOCD Release Processes:
  3. - @ref releasewhy - Explain the motivations for producing
  4. releases on a regular basis.
  5. - @ref releasewho - Describes the responsibilities and
  6. authority required to produce official OpenOCD releases.
  7. - @ref releasewhen - Provides guidelines for scheduling
  8. activities for each release cycle.
  9. - @ref releasehow - Outlines all of the steps for the
  10. processes used to produce and release the package source archives.
  11. - @ref releasescript - Introduces the automated @c script.
  12. @section releasewhy Why Produce Releases?
  13. The OpenOCD maintainers should produce <i>releases</i> periodically. This
  14. section gives several reasons to explain the reasons for making releases
  15. on a regular basis. These reasons lead to motivation for developing and
  16. following a set of <i>release processes</i>. The actual processes are
  17. described in the remainder of the @ref releases sections.
  18. At any time, a "source archives" can be produced by running 'make dist'
  19. in the OpenOCD project tree. With the 0.2.0 release, this command will
  20. produce openocd-\<version\>.{tar.gz,tar.bz2,zip} archives. These files
  21. will be suitable for being released when produced properly.
  22. When released for users, these archives present several important
  23. advantages when contrasted to using the Subversion repository:
  24. -# They allow others to package and distribute the code to users.
  25. -# They build easier for developers, because they contain
  26. a working configure script that was produced by the Release Manager.
  27. -# They prevent users from trying a random HEAD revision of the trunk.
  28. -# They free developers from answering questions about trunk breakage.
  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. -# Produce successive sets of release archives cleanly and consistently.
  34. -# Implementable as a script that automates the critical release steps.
  35. -# Prevent human operators from producing bad releases, when possible.
  36. -# Allow scheduling and automation of release process milestones.
  37. The current release processes are documented in the following sections.
  38. They attempt to meet these design goals, but there may improvements
  39. remaining to be made toward automating the process.
  40. @section releaseversions Release Versions
  41. The OpenOCD version string is composed of three numeric components
  42. separated by two decimal points: @c x.y.z, where @c x is the @a major
  43. version number, @c y is the @a minor number, and @c z is the @a micro.
  44. For a <i>bug-fix</i> release, the micro version number will be non-zero
  45. (<code>z > 0</code>). For a <i>minor release</i>, the micro version
  46. number will be zero (<code>z = 0</code>). For a <i>major releases</i>,
  47. the minor version will @a also be zero (<code>y = 0, z = 0</code>).
  48. The trunk and all branches should have the tag '-in-development' in
  49. their version number. This tag helps developers identify reports
  50. created from the Subversion repository, and it can be detected and
  51. manipulated by the release script. Specifically, this tag will be
  52. removed and re-added during the release process; it should never be
  53. manipulated by developers in submitted patches.
  54. @subsection releaseversionsdist Patched Versions
  55. Distributors of patched versions of OpenOCD are encouraged to extend
  56. the version string when producing external releases, as this helps to
  57. identify your particular distribution series.
  58. @subsection releaseversionsdist Version Processes
  59. The release process includes version number manipulations to the tree
  60. being released, ensuring that all numbers are incremented at the right
  61. time and in the proper locations of the repository.
  62. The version numbers for any branch should monotonically
  63. increase to the next successive integer, except when reset to zero
  64. during major or minor releases. The community should decide when
  65. major and minor milestones will be released.
  66. @section releasewho Release Manager
  67. OpenOCD archive releases will be produced by an individual filling the
  68. role of <i>Release Manager</i>, hereafter abbreviated as <i>RM</i>. This
  69. individual determines the schedule and executes the release processes
  70. for the community.
  71. @subsection releasewhohow RM Authority
  72. Each release requires one individual to fulfill the RM role; however,
  73. graceful transitions of this authority may take place at any time. The
  74. current RM may transfer their authority to another contributor in a post
  75. to the OpenOCD development mailing list. Such delegation of authority
  76. must be approved by the individual that will receive it and the
  77. community of maintainers. Initial arrangements with the new RM should
  78. be made off-list, as not every contributor wants these responsibilities.
  79. @subsection releasewhowhat RM Responsibilities
  80. In addition to the actual process of producing the releases, the RM is
  81. responsible for keeping the community informed of all progress through
  82. the release cycle(s) being managed. The RM is responsible for managing
  83. the changes to the package version, though the release tools should
  84. manage the tasks of adding or removing any required development branch
  85. tags and incrementing the version.
  86. @section releasewhen Release Schedule
  87. The OpenOCD release process must be carried out on a periodic basis, so
  88. the project can realize the benefits presented in answer to the question,
  89. @ref releasewhy.
  90. Starting with the 0.2.0 release, the OpenOCD project should produce a
  91. new minor release every month or two, with a major release once a year.
  92. Bug fix releases could be provided more frequently. These release
  93. schedule goals may be adjusted in the future, after the project
  94. maintainers and distributors receive feedback and experience.
  95. More importantly, the statements made in this section do not create an
  96. obligation by any member of the OpenOCD community to produce new
  97. releases on regular schedule, now or in the future.
  98. @subsection releasewhenexample Sample Schedule
  99. The RM must pro-actively communicate with the community from the
  100. beginning of the development cycle through the delivery of the new
  101. release. This section presents guidelines for scheduling key points
  102. where the community must be informed of changing conditions.
  103. If T is the time of the next release, then the following schedule
  104. might describe some of the key milestones of the new release cycle:
  105. - T minus one month: start of new development cycle
  106. - T minus two weeks: announce pending trunk closure to new work
  107. - T minus one week: close trunk to new work, begin testing phase
  108. - T minus two days: call for final bug fixes
  109. - T minus one day: produce -rc packages and distribute to testers
  110. - T minus one hour: produce final packages and post on-line
  111. - T minus zero: Announce the release to our mailing list and the world.
  112. Some additional supplemental communication will be desirable. The above
  113. list omits the step-by-step instructions to daily release management.
  114. Individuals performing release management need to have the ability to
  115. interact proactively with the community as a whole, anticipating when
  116. such interaction will be required and giving ample notification.
  117. The next section explains why the OpenOCD project allows significant
  118. flexibility in the part of the development that precedes the release
  119. process.
  120. @note The OpenOCD project does not presently produce -rc packages. As
  121. such, the step suggested in the list above should be read as trying to
  122. stimulate others to test the project build and packaging on as many
  123. platforms as possible. This proposition will be palatable once release
  124. management tools have been committed to the tree.
  125. @subsection releasewhenflex Schedule Flexibility
  126. The Release Manager should attempt to follow the guidelines in this
  127. document, but the process of scheduling each release milestone should be
  128. community driven at the start. By the end, missing features that were
  129. scheduled for a release must be dropped by the Release Manager, rather
  130. than allowing the release cycle to be delayed while waiting for them.
  131. Despite any assurances this schedule may appear to give, the Release
  132. Manager cannot schedule the work that will be done on the project,
  133. when it will be submitted, review, and deemed suitable to be committed.
  134. In this way, the RM cannot act as a priest in a cathedral; OpenOCD uses
  135. the bazaar development model. The release schedule must adapt
  136. continuously in response to changes in the rate of churn.
  137. In particular, the suggested period of "one or two month" reflects some
  138. expectation of a fairly high rate of development. Fewer releases may be
  139. required if developers contribute less patches, and more releases may be
  140. desirable if the project continues to grow and experience high rates of
  141. community contribution. During each cycle, the RM should be tracking
  142. the situation and gathering feedback from the community .
  143. @section releasehow Release Process: Step-by-Step
  144. The release process may require a few iterations to work out any bugs.
  145. Even with the release script, some steps require clear user intervention
  146. -- and not only by the Release Manager.
  147. The following steps should be followed to produce each release:
  148. -# Produce final patches to the trunk (or release branch):
  149. -# Finalize @c NEWS file to describe the changes in the release
  150. - This file is Used to automatically post "blurbs" about the project.
  151. - This material should be produced during the development cycle.
  152. - Add a new item for each @c NEWS-worthy contribution, when committed.
  153. -# bump library version if our API changed (not yet required)
  154. -# Remove -in-development tag from package version:
  155. - For major/minor releases, remove version tag from trunk, @a or
  156. - For bug-fix releases, remove version tag from release branch.
  157. -# Branch or tag the required tree in the Subversion repository:
  158. - Tags and branches for releases must be named consistently: @par
  160. - For a major/minor release from the main trunk, the code should be
  161. branched and tagged in the repository:
  162. @verbatim
  163. svn cp .../trunk .../branches/${RELEASE_BRANCH}
  164. svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
  165. @endverbatim
  166. - For bug-fix releases produced in their respective branch, a tag
  167. should be created in the repository:
  168. @verbatim
  169. svn cp .../branches/${RELEASE_BRANCH} .../tags/${RELEASE_TAG}
  170. @endverbatim
  171. -# Prepare to resume normal development activities:
  172. - Archive @c NEWS file as <code>doc/news/NEWS-${PACKAGE_VERSION}</code>.
  173. - Create a new @c NEWS file for the next release
  174. - For major/minor release from the trunk:
  175. -# Bump major or minor package version in trunk.
  176. -# Restore version tag to trunk and release branch.
  177. - For bug-fix releases from a release branch:
  178. -# Bump bug-fix version in release branch.
  179. -# Restore version tag to release branch.
  180. -# Produce the package source archives:
  181. -# Start with a clean working copy, used for producing releases only.
  182. -# Switch to release tag branch: svn switch .../${RELEASE_TAG}
  183. -# produce a ChangeLog for the release (using svn2cl).
  184. -# @c bootstrap, @c configure, and @c make the package.
  185. -# Run <code>make distcheck</code> to produce the distribution archives.
  186. -# Run <code>make maintainer-clean</code> verify the repository is empty.
  187. -# Publish documentation for the release:
  188. - Allow users to access the documentation for each of our releases.
  189. - Place static copies of the following files on the project website:
  190. - @c NEWS: to provide a blurb for each release
  191. - @c ChangeLog: to show exactly what has been changed
  192. - User Guide, Developer Manual: to allow easy on-line viewing
  193. -# Upload packages and post announcements of their availability:
  194. -# Release packages into files section of berliOS project site:
  195. -# Create the new release for the new version.
  196. -# Provide @c NEWS and ChangeLog files, as requested.
  197. -# Upload files via FTP to
  198. -# Edit descriptions for each file.
  199. -# Send E-mail Release Notice
  200. -# Post announcement e-mail to the openocd-development list.
  201. -# Announce updates on and other trackers.
  202. -# Submit big updates to news feeds (e.g. Digg, Reddit, etc.).
  203. @section releasescript The Release Script
  204. Many of the processes described in the last section are no longer
  205. entrusted to humans. Instead, the @c script provides
  206. automation of the mechanical steps.
  207. Presently, the @c script automates steps 1(c) through 4,
  208. allowing the Release Manager from perform these tasks in easy steps.
  209. The following task still need to be automated:
  210. - Step 5: produce documentation for website using released source archive.
  211. - Step 6(a): package archive upload process.
  212. - Step 6(b): package announcement e-mail process.
  213. - Step 6(c): post files and announce them using releaseforge.
  214. In addition, support for '-rc' releases needs to be added.
  215. @subsection releasescriptcmds Release Script Commands
  216. The following output was taken from the release script:
  217. @verbatim
  218. usage: tools/ [options] <command>
  219. Main Commands:
  220. info Show a summary of the next pending release.
  221. release Release the current tree as an archive.
  222. upload Upload archives to berliOS project site
  223. Build Commands:
  224. bootstrap Prepare the working copy for configuration and building.
  225. configure Configures the package; runs bootstrap, if needed.
  226. build Compiles the project; runs configure, if needed.
  227. Packaging Commands:
  228. changelog Generate a new ChangeLog using svn2cl.
  229. package Produce new distributable source archives.
  230. stage Move archives to staging area for upload.
  231. Repository Commands:
  232. commit Perform branch and tag, as appropriate for the version.
  233. branch Create a release branch from the project trunk.
  234. tag Create a tag for the current release branch.
  235. Other Commands:
  236. version ... Perform version number and tag manipulations.
  237. clean Forces regeneration of results.
  238. clean_all Removes all traces of the release process.
  239. help Provides this list of commands.
  240. For more information about this script, see the Release Processes page
  241. in the OpenOCD Developer's Manual (doc/manual/release.txt).
  242. WARNING: This script should be used by the Release Manager ONLY.
  243. @endverbatim
  244. Run <code>tools/ help</code> for current command support.
  245. @subsection releasescriptenv Release Script Options
  246. The @c script recognizes some command-line options that
  247. affect its behavior:
  248. - @c --live : Use this option to perform a live release.
  249. When this option has been given, the release commands will affect
  250. the repository; otherwise, the script reports the actions to take,
  251. and it produces archives that are unsuitable for public release.
  252. @note Only the Release Manager should use the @c --live option, as
  253. it will make permanent changes to the Subversion repository that
  254. cannot be undone.
  255. @subsection releasescriptenv Release Script Environment
  256. The @c script recognizes some environment variables which
  257. affect its behavior:
  258. - @c CONFIG_OPTS : Passed as options to the configure script.
  259. - @c MAKE_OPTS : Passed as options to the 'make' processes.
  260. @section releasetutorial Release Tutorials
  261. This section provides tutorials for using the Release Script to perform
  262. common release tasks.
  263. @subsection releasetutorialsetup Release Tutorial Setup
  264. The tutorials in this section assume the following environment
  265. variables have been set properly:
  266. @verbatim
  267. SVN_USER="maintainer"
  268. SVN_URL="https://${SVN_USER}"
  269. @endverbatim
  270. @subsection releasetutorialminor Minor Release Tutorial
  271. This section provides a step-by-step tutorial for a Release Manager to
  272. use to run the @c script to produce a minor release.
  273. If the proper environment has been set, the following steps will produce
  274. a new minor release:
  275. -# Check out (or update) the project trunk from the berliOS repository:
  276. @code
  277. svn checkout "${SVN_URL}/trunk" openocd-trunk
  278. @endcode
  279. -# Change to the new working copy directory:
  280. @code
  281. cd openocd-trunk
  282. @endcode
  283. -# Run @c to produce the minor release:
  284. @code
  285. tools/ all
  286. @endcode
  287. @subsection releasetutorialmicro Bug-Fix Release Tutorial
  288. This section provides a step-by-step tutorial for a Release Manager to
  289. use to run the @c script to produce a bug-fix release.
  290. In addition to the environment variables described in the introduction
  291. to these tutorials, the following variables are also used in the
  292. instructions for this section:
  293. @verbatim
  296. @endverbatim
  297. If the proper environment has been set, the following steps will produce
  298. a new bug-fix release:
  299. -# Check out (or update) the release branch from the project repository:
  300. @code
  301. svn checkout "${SVN_URL}/branches/${PACKAGE_BRANCH}" "${PACKAGE_BRANCH}"
  302. @endcode
  303. @code
  304. cd "${PACKAGE_BRANCH}"
  305. @endcode
  306. -# Run @c to produce the bug-fix release:
  307. @code
  308. tools/ all
  309. @endcode
  310. @section releasetodo Release Script Shortcomings
  311. Improved automated packaging and distribution of OpenOCD requires more
  312. patching of the configure script. The final release script should be
  313. able to manage most steps of the processes. The steps requiring user
  314. input could be guided by an "assistant" that walks the Release Manager
  315. through the process from beginning to end, performing basic sanity
  316. checks on their various inputs (e.g. the @c NEWS blurb).
  317. */
  318. /** @file
  319. This file contains the @ref releases page.
  320. */