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.

466 lines
22 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 releasescriptcmds - 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 properly versioned and released for users, these archives present
  23. several important advantages compared to using the source repository
  24. (including snapshots downloaded from that repository using gitweb):
  25. -# They allow others to package and distribute the code using
  26. consistent version labels. Users won't normally need to care
  27. whose package they use, just the version of OpenOCD.
  28. -# They contain a working configure script and makefiles, which
  29. were produced as part of creating the archive.
  30. -# Because they have been formally released by the project, users
  31. don't need to try a random work-in-process revision. Releasing
  32. involves spending some time specifically on quality improvments,
  33. including bugfixing source code and documentation.
  34. -# They provide developers with the flexibility needed to address
  35. larger issues, which sometimes involves temporary breakage.
  36. Hopefully, this shows several good reasons to produce regular releases,
  37. but the release processes were developed with some additional design
  38. goals in mind. Specifically, the releases processes should have the
  39. following properties:
  40. -# Produce successive sets of archives cleanly and consistently.
  41. -# Implementable as a script that automates the critical steps.
  42. -# Prevent human operators from producing broken packages, when possible.
  43. -# Allow scheduling and automation of building and publishing milestones.
  44. The current release processes are documented in the following sections.
  45. They attempt to meet these design goals, but improvements may still
  46. need to be made.
  47. @subsection version_labels Version Labels
  48. Users can display the OpenOCD version string in at least two
  49. ways. The command line <code>openocd -v</code> invocation
  50. displays it; as does the Tcl <code>version</code> command.
  51. Labels for released versions look like <em>0.3.0</em>, or
  52. <em>0.3.0-rc1</em> for a preliminary release.
  53. Non-released (developer) versions look like <em>0.3.0-dev</em>,
  54. or <em>0.3.0-rc1-dev</em>.
  55. In all cases, additional tags may be appended to those base
  56. release version labels.
  57. The <code>tools/release/</code> script is used to
  58. manipulate version IDs found in the source tree.
  59. @subsubsection releaseversions Release Versions and Tags
  60. The OpenOCD version string is composed of three numeric components
  61. separated by two decimal points: @c x.y.z, where @c x is the @a major
  62. version number, @c y is the @a minor number, and @c z is the @a micro.
  63. For any <em>bug-fix</em> release, the micro version number will be non-zero
  64. (<code>z > 0</code>). For a <i>minor release</i>, the micro version
  65. number will be zero (<code>z = 0</code>). For a <i>major releases</i>,
  66. the minor version will @a also be zero (<code>y = 0, z = 0</code>).
  67. After these required numeric components, release version strings
  68. may contain tags such as as <em>-rc1</em> or <em>-rc2</em>.
  69. These 'rc' tags indicate "release candidate" versions of the package.
  70. Like major/minor/micro numbers, these are updated
  71. as part of the release process.
  72. The release process includes version number manipulations to the tree
  73. being released, ensuring that all numbers are incremented (or rolled
  74. over) at the right time and in the proper locations of the repository.
  75. One of those manipulations creates a repository tag matching that
  76. release's version label.
  77. @subsubsection releaseversionsdist Packager Versions
  78. Distributors of patched versions of OpenOCD are encouraged to extend the
  79. version string with a unique version tag when producing external
  80. releases, as this helps to identify your particular distribution series.
  81. Knowing that a release has such patches can be essential to tracking
  82. down and fixing bugs.
  83. Packager version tags should always be suffixes to the version
  84. code from the OpenOCD project, signifying modifications to the
  85. original code base. Each packager release should have a unique
  86. version.
  87. For example, the following command will add a 'foo' tag to the
  88. script of a local copy of the source tree, giving
  89. a version label like <em>0.3.0-foo</em>:
  90. @code
  91. tools/release/ version tag add foo
  92. @endcode
  93. This command will modify the script in your working copy
  94. only. After running the @c bootstrap sequence, the tree can be patched
  95. and used to produce your own derived versions. You might check that
  96. change into a private branch of your git tree, along with the other
  97. patches you are providing.
  98. You can also "bump" those tags (so "foo1" becomes "foo2" etc)
  99. each time a derived package is released, incrementing the tag's
  100. version to facilitate tracking the changes you have distributed.
  101. @code
  102. tools/release/ version bump tag foo
  103. @endcode
  104. Of course, any patches in your branches must be provided to
  105. your customers, and be in conformance with the GPL. In most
  106. cases you should also work to merge your improvements to the
  107. mainline tree.
  108. @subsubsection version_tags Development Versions and Tags
  109. Everything except formal releases should have the tag <em>-dev</em>
  110. in their version number. This helps developers identify reports
  111. created from non-release versions, and it can be detected and
  112. manipulated by the release script. Specifically, this tag will be
  113. removed and re-added during the release process; it should never be
  114. manipulated by developers in submitted patches.
  115. Versions built from developer trees may have additional tags.
  116. Trees built from git snapshots have <em>snapshot</em> tags.
  117. When built from a "live" git tree, tags specify
  118. specific git revisions:
  119. 0.3.0-rc1-dev-00015-gf37c9b8-dirty
  120. indicates a development tree based on git revison f37c9b8
  121. (a truncated version of a SHA1 hash) with some non-git
  122. patches applied (the <em>dirty</em> tag). This information
  123. can be useful when tracking down bugs.
  124. (Note that at this writing, the tags do not directly
  125. correspond to <code>git describe</code> output. The
  126. hash ID can be used with <code>git show</code>, but
  127. the relevant repository tag isn't <em>0.3.0-rc1-dev</em>;
  128. this might change in the future.)
  129. @section releasewho Release Manager
  130. OpenOCD archive releases will be produced by an individual filling the
  131. role of <i>Release Manager</i>, hereafter abbreviated as <i>RM</i>. This
  132. individual determines the schedule and executes the release processes
  133. for the community.
  134. @subsection releasewhohow RM Authority
  135. Each release requires one individual to fulfill the RM role; however,
  136. graceful transitions of this authority may take place at any time. The
  137. current RM may transfer their authority to another contributor in a post
  138. to the OpenOCD development mailing list. Such delegation of authority
  139. must be approved by the individual that will receive it and the
  140. community of maintainers. Initial arrangements with the new RM should
  141. be made off-list, as not every contributor wants these responsibilities.
  142. @subsection releasewhowhat RM Responsibilities
  143. In addition to the actual process of producing the releases, the RM is
  144. responsible for keeping the community informed of all progress through
  145. the release cycle(s) being managed. The RM is responsible for managing
  146. the changes to the package version, though the release tools should
  147. manage the tasks of adding or removing any required development branch
  148. tags and incrementing the version.
  149. These responsibilities matter most towards the end of the release
  150. cycle, when the RM creates the first RC and all contributors enter
  151. a quality-improvement mode. The RM works with other contributors
  152. to make sure everyone knows what kinds of fixes should merge, the
  153. status of major issues, and the release timetable.
  154. In particular, the RM has the final decision on whether a given
  155. bug should block the release.
  156. @section releasewhen Release Schedule
  157. The OpenOCD release process must be carried out on a periodic basis, so
  158. the project can realize the benefits presented in answer to the question,
  159. @ref releasewhy.
  160. Starting with the 0.2.0 release, the OpenOCD project expects to produce
  161. new releases every few months.
  162. Bug fix releases could be provided more frequently. These release
  163. schedule goals may be adjusted in the future, after the project
  164. maintainers and distributors receive feedback and experience.
  165. More importantly, the statements made in this section do not create an
  166. obligation by any member of the OpenOCD community to produce new
  167. releases on regular schedule, now or in the future.
  168. @subsection releasewhenexample Sample Schedule
  169. The RM must pro-actively communicate with the community from the
  170. beginning of the development cycle through the delivery of the new
  171. release. This section presents guidelines for scheduling key points
  172. where the community must be informed of changing conditions.
  173. If Tn is the time of release n, then the following schedule
  174. might describe some key T0-to-T1 release cycle milestones.
  175. - T0 ... End of T0 release cycle. T1 cycle starts, with merge
  176. window opening. Developers begin to merge queued work.
  177. - <em>... several weeks of merge window ...</em>
  178. - RC1 ... Close mainline to new work. Produce RC1
  179. release, begin testing phase; developers are in "bugfix mode",
  180. all other work is queued; send out planned endgame schedule.
  181. - RC2 ... Produce RC2 and send schedule update to
  182. mailing list, listing priorities for remaining fixes
  183. - <em>... more RC milestones, until ready ...</em>
  184. - T1: End of T1 release cycle. T2 cycle starts, with merge
  185. window opening. Developers begin to merge queued work.
  186. Note that until it happens, any date for T1 is just a goal.
  187. Critical bugs prevent releases from happening. We are just
  188. beginning to use this window-plus-RCs process, so the lengths
  189. of the merge windows versus the RC phase is subject to change.
  190. Most projects have RC phases of a month or more.
  191. Some additional supplemental communication will be desirable. The above
  192. list omits the step-by-step instructions to daily release management.
  193. Individuals performing release management need to have the ability to
  194. interact proactively with the community as a whole, anticipating when
  195. such interaction will be required and giving ample notification.
  196. The next section explains why the OpenOCD project allows significant
  197. flexibility in the part of the development that precedes the release
  198. process.
  199. @subsection releasewhenflex Schedule Flexibility
  200. The Release Manager should attempt to follow the guidelines in this
  201. document, but the process of scheduling each release milestone should be
  202. community driven at the start. Features that don't complete before
  203. the merge window closes can be held (perhaps in some branch) until
  204. the next merge window opens, rather than delaying the release cycle.
  205. The Release
  206. Manager cannot schedule the work that will be done on the project,
  207. when it will be submitted, reviewed, and deemed suitable to be committed.
  208. That is, the RM cannot act as a priest in a cathedral; OpenOCD uses
  209. the bazaar development model. The release schedule must adapt
  210. continuously in response to changes in the rate of work.
  211. Fewer releases may be
  212. required if developers contribute less patches, and more releases may be
  213. desirable if the project continues to grow and experience high rates of
  214. community contribution. During each cycle, the RM should be tracking
  215. the situation and gathering feedback from the community.
  216. @section releasehow Release Process: Step-by-Step
  217. The release process is not final; it may need more iterations
  218. to work out bugs.
  219. While there are release scripts, key steps require community
  220. support; the Release Manager isn't the only participant.
  221. The following steps should be followed to produce each release:
  222. -# Produce final patches using a local clone of mainline. Nobody
  223. except the RM should be committing anything. <em>Everyone with commit
  224. privileges needs to know and agree to this in advance!</em> Even the RM
  225. only commits a handful of updates as part of the release process
  226. itself ... to files which are part of the version identification scheme
  227. or release process; and to create the version tag; and then to open the
  228. merge window for the next release cycle.
  229. -# Finalize @c the NEWS file to describe the changes in the release
  230. - This file is used to automatically post "blurbs" about the project.
  231. - This material should have been produced during the development cycle,
  232. by adding items for each @c NEWS-worthy contribution, when committed
  233. during the merge window. (One part of closing the merge window, by
  234. opening the RC phase of the release, is the commitment to hold all
  235. further such contributions until the next merge window opens.)
  236. - The RM should make sure nothing important was omitted, as part of
  237. the RC1 cycle. From then on, no more updates to NEWS content should
  238. be needed (except to seed the process for the next release, or maybe
  239. if a significant and longstanding bug is fixed late in the RC phase).
  240. -# Bump library version if our API changed (not yet required)
  241. -# Update and commit the final package version in @c
  242. (The <code>tools/release/</code> script might help ensure
  243. the versions are named properly.):
  244. -# Remove @c -dev tag.
  245. -# Update any @c -rc tag:
  246. - If producing the final release from an -rc series, remove it
  247. - If producing the first RC in a series, add rc1
  248. - If producing the next RC in a series, bump the rc number
  249. -# Commit that version change, with a good descriptive comment.
  250. -# Create a git tag for the final commit, with a tag name matching
  251. the version string in <code></code> (including <em>-rcN</em>
  252. where relevant):
  253. @verbatim
  254. PACKAGE_VERSION="x.y.z"
  256. git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}"
  257. @endverbatim
  258. -# Do not push those changes to mainline yet; only builds using the
  259. source archives you will be creating should ever be labeled as
  260. official releases (with no "-dev" suffix). Since mainline is a
  261. development tree, these will be pushed later, as part of opening
  262. the merge window for the next release cycle (restoring the "-dev"
  263. suffix for that next release.) Those version and tag updates are
  264. the last ones to be included in the release being made.
  265. -# Produce the release files, using the local clone of the source
  266. tree which holds the release's tag and updated version in
  267. @c ... this is used only to produce the release, and
  268. all files should already be properly checked out.
  269. -# Run <code>tools/ package</code> to produce the
  270. source archives. This automatically bootstraps and
  271. configures the process.
  272. -# Run <code>tools/ stage</code> to create an @c archives
  273. directory with the release data, including MD5 and SHA1
  274. checksum files.
  275. -# Sanity check at least one of those archives, by extracting and
  276. configuring its contents, using them to build a copy of OpenOCD,
  277. and verifying that the result prints the correct release version
  278. in its startup banner. (For example,
  279. "configure --enable-ft2232_libftdi --enable-parport"
  280. then "make" and run "src/openocd -v" as a sanity check.)
  281. -# Run <code>make docs</code> to create the
  282. documentation which will be published.
  283. -# Upload packages and post announcements of their availability:
  284. -# Release packages into files section of project sites:
  285. -
  286. -# Under "Project Admin", use the "File Manager"
  287. -# Create a new folder under "openocd" named "${PACKAGE_VERSION}"
  288. -# Upload the @c NEWS file and mark it as the release notes.
  289. -# Upload the three source archive files, using the Web interface,
  290. into that folder. Verify the upload worked OK by checking the
  291. MD5 and SHA1 checksums computed by SourceForge against the
  292. versions created as part of staging the release.
  293. -# Also upload doc/openocd.pdf (the User's Guide) so the version
  294. matching each release will be easily available.
  295. -# Select each file in the release, and use the property panel
  296. to set its type and select the right release notes.
  297. - .tar.bz2: Linux, Mac
  298. - .tar.gz: BSD, Solaris, Others
  299. - .zip: Windows
  300. - For openocd.pdf just associate it with the right release notes.
  301. -# Create an project news update.
  302. -# Depending on how paranoid you're feeling today, verify the images by
  303. downloading them from the websites and making sure there are no
  304. differences between the downloaded copies and your originals.
  305. -# Publish User's and Developer's Guides to the project web sites:
  306. -# Use SCP to update the web site with PDF and HTML for the
  307. User's Guide, and HTML for the developer's guide ... you can
  308. instantiate a instance and set up symlinks
  309. from your home directory, to simplify this process.
  310. -# Post announcement e-mail to the openocd-development list.
  311. -# optionally:
  312. -# Post an update on the OpenOCD blog.
  313. -# Announce updates on and other trackers.
  314. -# Submit updates to news feeds (e.g. Digg, Reddit, etc.).
  315. -# Resume normal development on mainline, by opening the merge window for
  316. the next major or minor release cycle. (You might want to do this
  317. before all the release bits are fully published.)
  318. - Update the version label in the @c file:
  319. - Restore @c -dev version tag.
  320. - For a new minor release cycle, increment the release's minor number
  321. - For a new major release cycle, increment the release's major number
  322. and zero its minor number
  323. - Archive @c NEWS file as "<code>doc/news/NEWS-${PACKAGE_VERSION}</code>".
  324. - Create a new @c NEWS file for the next release
  325. - Commit those changes.
  326. - Push all the updates to mainline.
  327. - Last updates for the release, including the release tag (you
  328. will need to "git push --tags").
  329. - Updates opening the merge window
  330. - At this point, it's OK for commiters to start pushing changes
  331. which have been held off until the next release. (Any bugfixes to
  332. this release will be against a bug-fix release branch starting from
  333. the commit you tagged as this release, not mainline.)
  334. - Announce to the openocd-development list. Ideally, you will also
  335. be able to say who is managing the next release cycle.
  336. To start a bug-fix release branch:
  337. -# Create a new branch, starting from a major or
  338. minor release tag
  339. -# Restore @c -dev version tag.
  340. -# Bump micro version number in
  341. -# Backport bugfix patches from mainline into that branch.
  342. (Always be sure mainline has the fix first, so it's hard
  343. to just lose a bugfix.)
  344. -# Commit and push those patches.
  345. -# When desired, release as above ... except note that the next
  346. release of a bugfix branch is never a new major or minor release
  347. @subsection releasescriptcmds Release Script Commands
  348. The @c script automates some of the steps involved
  349. in making releases, simplifying the Release Manager's work.
  350. The release script can be used for two tasks:
  351. - Creating releases and starting a new release cycle:
  352. @code
  353. git checkout master
  354. tools/ --type=minor --final --start-rc release
  355. @endcode
  356. - Creating a development branch from a tagged release:
  357. @code
  358. git checkout 'v0.2.0'
  359. tools/ --type=micro branch
  360. @endcode
  361. Both of these variations make automatic commits and tags in your
  362. repository, so you should be sure to run it on a cloned copy before
  363. proceding with a live release.
  364. @subsection releasescriptopts Release Script Options
  365. The @c script recognizes some command-line options that
  366. affect its behavior:
  367. - The @c --start-rc indicates that the new development release cycle
  368. should start with @c -rc0. Without this, the @c -rc tag will be omitted,
  369. leading to non-monotonic versioning of the in-tree version numbers.
  370. - The @c --final indicates that the release should drop the @c -rc tag,
  371. to going from @c x.y.z-rcN-dev to x.y.z.
  372. @subsection releasescriptenv Release Script Environment
  373. The @c script recognizes some environment variables which
  374. affect its behavior:
  375. - @c CONFIG_OPTS : Passed as options to the configure script.
  376. - @c MAKE_OPTS : Passed as options to the 'make' processes.
  377. @section releasetutorial Release Tutorials
  378. This section should contain a brief tutorial for using the Release
  379. Script to perform release tasks, but the new script needs to be
  380. used for 0.3.0.
  381. @section releasetodo Release Script Shortcomings
  382. Improved automated packaging and distribution of OpenOCD requires more
  383. patching of the configure script. The final release script should be
  384. able to manage most steps of the processes. The steps requiring user
  385. input could be guided by an "assistant" that walks the Release Manager
  386. through the process from beginning to end, performing basic sanity
  387. checks on their various inputs (e.g. the @c NEWS blurb).
  388. */
  389. /** @file
  390. This file contains the @ref releases page.
  391. */