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.

release.txt 16 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 produce <i>releases</i> periodically for many
  14. reasons. This section provides the key reasons for making releases on a
  15. regular basis and why a set of <i>release processes</i> should be used
  16. to produce them.
  17. At any time, <i>source archives</i> can be produced by running
  18. <code>make dist</code> in the OpenOCD project tree. With the 0.2.0
  19. release, this command will package the tree into several popular archive
  20. formats: <code>openocd-\<version\>.{tar.gz,tar.bz2,zip}</code>. If
  21. produced properly, these files are suitable for release to the public.
  22. When released for users, these archives present several important
  23. advantages when contrasted to using the git repository:
  24. -# They allow others to package and distribute the code.
  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 work-in-process revision.
  28. -# They free developers from answering questions about mainline breakage.
  29. Hopefully, this shows several good reasons to produce regular releases,
  30. but the 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 archives cleanly and consistently.
  34. -# Implementable as a script that automates the critical steps.
  35. -# Prevent human operators from producing broken packages, when possible.
  36. -# Allow scheduling and automation of building and publishing 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. @subsection releaseversiontags Version Tags
  49. After these required numeric components, the version string may contain
  50. one or more <i>version tags</i>, such as '-rc1' or '-dev'.
  51. Mainline and all branches should have the tag '-dev' in
  52. their version number. This tag helps developers identify reports
  53. created from the git repository, and it can be detected and
  54. manipulated by the release script. Specifically, this tag will be
  55. removed and re-added during the release process; it should never be
  56. manipulated by developers in submitted patches.
  57. The 'rc' tags indicate a "release candidate" version of the package.
  58. This tag will also be manipulated by the automated release process.
  59. Additional tags may be used as necessary.
  60. @subsection releaseversionsdist Packager Versions
  61. Distributors of patched versions of OpenOCD are encouraged to extend the
  62. version string with a unique version tag when producing external
  63. releases, as this helps to identify your particular distribution series.
  64. For example, the following command will add a 'foo1' tag to the
  65. script of a local copy of the source tree:
  66. @code
  67. tools/ version bump tag foo
  68. @endcode
  69. This command will modify the script in your working copy
  70. only. After running the @c bootstrap sequence, the tree can be patched
  71. and used to produce your own derived versions. The same command can be
  72. used each time the derived package is released, incrementing the tag's
  73. version to facilitate tracking the changes you have distributed.
  74. @subsection releaseversionhow Version Processes
  75. The release process includes version number manipulations to the tree
  76. being released, ensuring that all numbers are incremented at the right
  77. time and in the proper locations of the repository.
  78. The version numbers for any branch should increase monotonically
  79. to the next successive integer, except when reset to zero
  80. during major or minor releases. The community should decide when
  81. major and minor milestones will be released.
  82. @section releasewho Release Manager
  83. OpenOCD archive releases will be produced by an individual filling the
  84. role of <i>Release Manager</i>, hereafter abbreviated as <i>RM</i>. This
  85. individual determines the schedule and executes the release processes
  86. for the community.
  87. @subsection releasewhohow RM Authority
  88. Each release requires one individual to fulfill the RM role; however,
  89. graceful transitions of this authority may take place at any time. The
  90. current RM may transfer their authority to another contributor in a post
  91. to the OpenOCD development mailing list. Such delegation of authority
  92. must be approved by the individual that will receive it and the
  93. community of maintainers. Initial arrangements with the new RM should
  94. be made off-list, as not every contributor wants these responsibilities.
  95. @subsection releasewhowhat RM Responsibilities
  96. In addition to the actual process of producing the releases, the RM is
  97. responsible for keeping the community informed of all progress through
  98. the release cycle(s) being managed. The RM is responsible for managing
  99. the changes to the package version, though the release tools should
  100. manage the tasks of adding or removing any required development branch
  101. tags and incrementing the version.
  102. @section releasewhen Release Schedule
  103. The OpenOCD release process must be carried out on a periodic basis, so
  104. the project can realize the benefits presented in answer to the question,
  105. @ref releasewhy.
  106. Starting with the 0.2.0 release, the OpenOCD project should produce a
  107. new minor release every month or two, with a major release once a year.
  108. Bug fix releases could be provided more frequently. These release
  109. schedule goals may be adjusted in the future, after the project
  110. maintainers and distributors receive feedback and experience.
  111. More importantly, the statements made in this section do not create an
  112. obligation by any member of the OpenOCD community to produce new
  113. releases on regular schedule, now or in the future.
  114. @subsection releasewhenexample Sample Schedule
  115. The RM must pro-actively communicate with the community from the
  116. beginning of the development cycle through the delivery of the new
  117. release. This section presents guidelines for scheduling key points
  118. where the community must be informed of changing conditions.
  119. If T is the time of the next release, then the following schedule
  120. might describe some of the key milestones of the new release cycle:
  121. - T minus one month: start of new development cycle
  122. - T minus two weeks: announce pending mainline closure to new work
  123. - T minus one week: close mainline to new work, begin testing phase
  124. - T minus two days: call for final bug fixes
  125. - T minus one day: produce -rc packages and distribute to testers
  126. - T minus one hour: produce final packages and post on-line
  127. - T minus zero: Announce the release to our mailing list and the world.
  128. Some additional supplemental communication will be desirable. The above
  129. list omits the step-by-step instructions to daily release management.
  130. Individuals performing release management need to have the ability to
  131. interact proactively with the community as a whole, anticipating when
  132. such interaction will be required and giving ample notification.
  133. The next section explains why the OpenOCD project allows significant
  134. flexibility in the part of the development that precedes the release
  135. process.
  136. @note The OpenOCD project does not presently produce -rc packages. As
  137. such, the step suggested in the list above should be read as trying to
  138. stimulate others to test the project build and packaging on as many
  139. platforms as possible. This proposition will be palatable once release
  140. management tools have been committed to the tree.
  141. @subsection releasewhenflex Schedule Flexibility
  142. The Release Manager should attempt to follow the guidelines in this
  143. document, but the process of scheduling each release milestone should be
  144. community driven at the start. By the end, missing features that were
  145. scheduled for a release must be dropped by the Release Manager, rather
  146. than allowing the release cycle to be delayed while waiting for them.
  147. Despite any assurances this schedule may appear to give, the Release
  148. Manager cannot schedule the work that will be done on the project,
  149. when it will be submitted, reviewed, and deemed suitable to be committed.
  150. In this way, the RM cannot act as a priest in a cathedral; OpenOCD uses
  151. the bazaar development model. The release schedule must adapt
  152. continuously in response to changes in the rate of churn.
  153. In particular, the suggested period of "one or two month" reflects some
  154. expectation of a fairly high rate of development. Fewer releases may be
  155. required if developers contribute less patches, and more releases may be
  156. desirable if the project continues to grow and experience high rates of
  157. community contribution. During each cycle, the RM should be tracking
  158. the situation and gathering feedback from the community.
  159. @section releasehow Release Process: Step-by-Step
  160. The release process may require a few iterations to work out any bugs.
  161. Even with the release script, some steps require clear user intervention
  162. -- and not only by the Release Manager.
  163. The following steps should be followed to produce each release:
  164. -# Produce final manual patches to mainline (or release branch):
  165. -# Finalize @c NEWS file to describe the changes in the release
  166. - This file is Used to automatically post "blurbs" about the project.
  167. - This material should be produced during the development cycle.
  168. - Add a new item for each @c NEWS-worthy contribution, when committed.
  169. -# Bump library version if our API changed (not yet required)
  170. -# Produce and tag the final revision in the git repository:
  171. - Update and commit the final package version in @c :
  172. -# Remove @c -dev tag.
  173. -# Remove @c -rc tag, if producing the final release from an -rc series.
  174. - Tags must be named consistently:
  175. @verbatim
  176. @endverbatim
  177. - Tag the final commit with a consistent GIT tag name and message:
  178. @verbatim
  179. PACKAGE_VERSION="x.y.z"
  181. git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}"
  182. @endverbatim
  183. -# Prepare to resume normal development on the branch:
  184. - Restore @c -dev and -@c -rc0 version tags.
  185. - To start a new major (or minor) release cycle on the @c master branch:
  186. - Bump major (or minor) package version, zeroing sub-components.
  187. - Add -rc0 version tag:
  188. - This insures casual releases from GIT always increase monotonically.
  189. - For example, a major increment after releasing 1.2.3 starts 2.0.0-rc0-dev.
  190. - Archive @c NEWS file as "<code>doc/news/NEWS-${PACKAGE_VERSION}</code>".
  191. - Create a new @c NEWS file for the next release
  192. - To start a bug-fix release on a non-master branch:
  193. -# Bump bug-fix version.
  194. - To start another release candidate on a major or minor branch:
  195. -# Bump rc tag.
  196. -# Produce the package source archives:
  197. -# Start with a clean working copy, used for producing releases only.
  198. -# Checkout the appropriate tag:
  199. <code>git checkout $(git tag ) "${PACKAGE_VERSION}"</code>
  200. -# Produce a ChangeLog for the release (using @c git2cl).
  201. -# @c bootstrap, @c configure, and @c make the package.
  202. -# Run <code>make distcheck</code> to produce the distribution archives.
  203. -# Run <code>make maintainer-clean</code> verify the repository is empty.
  204. -# Create signature files using @c md5sum, @c sha1sum, etc.
  205. -# Publish documentation for the release:
  206. - Allow users to access the documentation for each of our releases.
  207. - Place static copies of the following files on the project website:
  208. - @c NEWS: to provide a blurb for each release
  209. - @c ChangeLog: to show exactly what has been changed
  210. - User Guide, Developer Manual: to allow easy on-line viewing
  211. -# Upload packages and post announcements of their availability:
  212. -# Release packages into files section of project sites:
  213. -
  214. -# Create a new folder named "${PACKAGE_VERSION}"
  215. -# Select new folder as the target for uploads.
  216. -# Upload files via Web interface into new
  217. -# Set platform types for each archive:
  218. - .tar.bz2: Linux, Mac
  219. - .tar.gz: BSD, Solaris, Others
  220. - .zip: Windows
  221. - Berlios:
  222. -# Create the new release for the new version.
  223. -# Provide @c NEWS and ChangeLog files, as requested.
  224. -# Upload files via FTP to
  225. -# Edit descriptions for each file.
  226. -# Click button to send E-mail Release Notice.
  227. -# Post announcement e-mail to the openocd-development list.
  228. -# Announce updates on and other trackers.
  229. -# Submit big updates to news feeds (e.g. Digg, Reddit, etc.).
  230. @section releasescript The Release Script
  231. Many of the processes described in the last section are no longer
  232. entrusted to humans. Instead, the @c script provides
  233. automation of the mechanical steps.
  234. Presently, the @c script automates steps 2 through 4,
  235. allowing the Release Manager from perform these tasks in easy steps.
  236. The following task still need to be automated:
  237. - Step 5: produce documentation for website using released source archive.
  238. - Step 6(a): package archive upload process.
  239. - Step 6(b): package announcement e-mail process.
  240. - Step 6(c): post files and announce them using releaseforge.
  241. @subsection releasescriptcmds Release Script Commands
  242. The release script can be used for two tasks:
  243. - Creating releases and starting a new release cycle:
  244. @code
  245. git checkout master
  246. tools/ --type=minor --final --start-rc release
  247. @endcode
  248. - Creating a development branch from a tagged release:
  249. @code
  250. git checkout 'v0.2.0'
  251. tools/ --type=micro branch
  252. @endcode
  253. Both of these variations make automatic commits and tags in your
  254. repository, so you should be sure to run it on a cloned copy before
  255. proceding with a live release.
  256. @subsection releasescriptopts Release Script Options
  257. The @c script recognizes some command-line options that
  258. affect its behavior:
  259. - The @c --start-rc indicates that the new development release cycle
  260. should start with @c -rc0. Without this, the @c -rc tag will be omitted,
  261. leading to non-monotonic versioning of the in-tree version numbers.
  262. - The @c --final indicates that the release should drop the @c -rc tag,
  263. to going from @c x.y.z-rcN-dev to x.y.z.
  264. @subsection releasescriptenv Release Script Environment
  265. The @c script recognizes some environment variables which
  266. affect its behavior:
  267. - @c CONFIG_OPTS : Passed as options to the configure script.
  268. - @c MAKE_OPTS : Passed as options to the 'make' processes.
  269. @section releasetutorial Release Tutorials
  270. This section should contain a brief tutorial for using the Release
  271. Script to perform release tasks, but the new script needs to be
  272. used for 0.3.0.
  273. @section releasetodo Release Script Shortcomings
  274. Improved automated packaging and distribution of OpenOCD requires more
  275. patching of the configure script. The final release script should be
  276. able to manage most steps of the processes. The steps requiring user
  277. input could be guided by an "assistant" that walks the Release Manager
  278. through the process from beginning to end, performing basic sanity
  279. checks on their various inputs (e.g. the @c NEWS blurb).
  280. */
  281. /** @file
  282. This file contains the @ref releases page.
  283. */