444 lines
16 KiB
HTML
444 lines
16 KiB
HTML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
<title>EPICS Release Procedures & Checklist</title>
|
|
<style type="text/css" media="print">
|
|
<!--
|
|
body {
|
|
font: 10.5pt/12pt Arial, Helvetica, sans-serif;
|
|
}
|
|
table {
|
|
border-collapse: collapse;
|
|
border: thin solid black;
|
|
}
|
|
tt {
|
|
font: 9pt/11pt "Courier New", fixed;
|
|
}
|
|
td,th {
|
|
padding: 2pt 4pt;
|
|
vertical-align: top
|
|
}
|
|
td blockquote {
|
|
page-break-inside: avoid;
|
|
margin-right: 0;
|
|
}
|
|
-->
|
|
</style>
|
|
</head>
|
|
|
|
<body>
|
|
<h1>EPICS Base Release Procedures & Checklist</h1>
|
|
|
|
<p>This document describes the procedures and provides a checklist of tasks
|
|
that should be performed when creating production releases of EPICS Base.</p>
|
|
|
|
<h3>The Release Process</h3>
|
|
|
|
<p>We used to have one written down here, but we weren't following it very
|
|
closely so now the decision to make a new release is taken during the Core
|
|
Developers bi-weekly meetings in an informal manner. The steps detailed below
|
|
were written to remind Andrew (or anyone else who does the release) about
|
|
everything that has to be done since it's so easy to miss steps.</p>
|
|
|
|
<h3>Roles</h3>
|
|
|
|
<p>The following roles are used below:</p>
|
|
|
|
<dl>
|
|
<dt><strong>Release Manager</strong></dt>
|
|
<dd>Responsible for managing and tagging the release</dd>
|
|
<dt><strong>Core Developers</strong></dt>
|
|
<dd>Responsible for maintaining the EPICS software</dd>
|
|
<dt><strong>Application Developers</strong></dt>
|
|
<dd>Responsible for support modules that depend on EPICS Base.</dd>
|
|
<dt><strong>Website Editors</strong></dt>
|
|
<dd>Responsible for the EPICS websites</dd>
|
|
</dl>
|
|
|
|
<form>
|
|
<table border="1" width="100%">
|
|
<tbody>
|
|
<tr>
|
|
<th>Check</th>
|
|
<th>Who</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="3">Preparing for a release</th>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Release Manager</td>
|
|
<td>Notify core developers about the upcoming release and ask about any
|
|
remaining tasks that must be finished.</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>All developers</td>
|
|
<td>Check the bug tracker for any outstanding items and handle
|
|
appropriately.</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Release Manager</td>
|
|
<td>Set a Feature Freeze date, by which time all Git branches for
|
|
enhancements and new functionality should have been merged. After this
|
|
date, commits and merges should only be made to fix problems that show
|
|
up during testing.</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Release Manager<br />
|
|
& all developers</td>
|
|
<td>Ensure that documentation will be updated before the release date:
|
|
<ul>
|
|
<li>Release Notes</li>
|
|
<li>Doxygen annotations</li>
|
|
<li>Other documents</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Release Manager</td>
|
|
<td>Review and update this checklist for the upcoming release.
|
|
Update the release version number in the tags and messages below.</td>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="3">Testing</th>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Platform Developers</td>
|
|
<td>Run the internal test programs on all available host platforms using
|
|
<blockquote><tt>
|
|
make -s runtests
|
|
</tt></blockquote></td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Platform Developers</td>
|
|
<td>Run the CA client side regression tests on all available host
|
|
platforms.</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Platform Developers</td>
|
|
<td>Check that all makeBaseApp templates build and run properly, all
|
|
<i>xxxApp</i> and <i>xxxBoot</i> types and any internal options, e.g.
|
|
setting <tt>STATIC_BUILD=YES</tt> or using a different
|
|
<tt>INSTALL_LOCATION</tt> in configure/CONFIG_SITE.</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Platform Developers</td>
|
|
<td>Build the SNL Sequencer against this version of Base, and check that
|
|
the makeBaseApp example builds and runs correctly with it.</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Application Developers</td>
|
|
<td>Build external applications against this version of Base on all
|
|
available platforms and test as appropriate. Application code changes
|
|
may be necessary where the EPICS Base APIs have been modified.</td>
|
|
</tr>
|
|
<tr>
|
|
<td> </td>
|
|
<td>Release Manager</td>
|
|
<td>Check that documentation has been updated:
|
|
<ul>
|
|
<li>Release Notes</li>
|
|
<li>Doxygen annotations</li>
|
|
<li>Other documents</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th colspan="3" id="ReleaseApproval">
|
|
Release Approval</th>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Core Developers</td>
|
|
<td>Reach a consensus that the software is ready to release.</td>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="3">Creating the final release version</th>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Release Manager</td>
|
|
<td>
|
|
<p><b>For each external submodule</b> in turn (assuming it has not been
|
|
tagged yet):</p>
|
|
<ol>
|
|
<li><tt>git grep UNRELEASED</tt> and insert the module version to any
|
|
doxygen annotations that have a <tt>@since UNRELEASED</tt> comment.
|
|
Commit (don't push yet).</li>
|
|
|
|
<li>Check that the module's Release Notes have been updated to cover
|
|
all changes; add items as necessary, and set the module version
|
|
number and release date if appropriate.
|
|
Commit these changes (don't push).</li>
|
|
|
|
<li>Edit the module's release version file
|
|
<tt>configure/CONFIG_<i>module</i>_VERSION</tt> and the
|
|
<tt>Doxyfile</tt>s in the top-level and/or documentation
|
|
directories. In these, set <tt>DEVELOPMENT_FLAG</tt> to 0 and remove
|
|
<tt>-dev</tt> from the <tt>PROJECT_NUMBER</tt> string. Commit these
|
|
changes (don't push):
|
|
<blockquote><tt>
|
|
git ci -m 'Final commit for <module-version>'
|
|
</tt></blockquote>
|
|
</li>
|
|
|
|
<li>Tag the module:
|
|
<blockquote><tt>
|
|
git tag -m 'ANJ: Tag for EPICS 7.0.8.2' <module-version>
|
|
</tt></blockquote>
|
|
</li>
|
|
|
|
<li>Generate documentation or Release Notes using one of these:
|
|
<ul>
|
|
<li>For older modules with a RELEASE_NOTES.md file convert it to
|
|
HTML and view in a browser to check the formatting as follows:
|
|
<blockquote><tt>
|
|
cd base-7.0/modules/<module>/documentation<br />
|
|
pandoc -f gfm -t html -o RELEASE_NOTES.html RELEASE_NOTES.md
|
|
</tt></blockquote>
|
|
|
|
<li>For newer modules with release_notes.dox file, generate the
|
|
new github-pages website as follows:
|
|
<blockquote><tt>
|
|
cd base-7.0/modules/<module>/documentation<br />
|
|
make commit
|
|
git push --force upstream gh-pages
|
|
</tt></blockquote>
|
|
<i>Q: Delay this <tt>git push</tt> until later?</i></li>
|
|
</ul></li>
|
|
|
|
<li>Update the git submodule on the Base-7.0 branch to the
|
|
newly-tagged version, check the module's status matches the tag:
|
|
<blockquote><tt>
|
|
cd base-7.0/modules<br />
|
|
git add <module><br />
|
|
git submodule status --cached
|
|
</tt></blockquote>
|
|
Don't commit the submodule updates yet.
|
|
</li>
|
|
|
|
<li>Edit the module's release version file
|
|
<tt>configure/CONFIG_<i>module</i>_VERSION</tt> and its top-level
|
|
<tt>Doxyfile</tt>; increment the <tt>MAINTENANCE_VERSION</tt>, set
|
|
the <tt>DEVELOPMENT_FLAG</tt> value to 1, and update the
|
|
<tt>PROJECT_NUMBER</tt> string, appending <tt>-dev</tt> to the new
|
|
module version number. Commit changes.</li>
|
|
|
|
<li>Push commits and the new tag to the submodule's GitHub repository
|
|
(assumed to be the <tt>upstream</tt> remote):
|
|
<blockquote><tt>
|
|
cd base-7.0/modules/<module><br />
|
|
git push --follow-tags upstream master
|
|
</tt></blockquote>
|
|
</li>
|
|
|
|
</ol>
|
|
<p><b>After all submodules complete</b> commit the submodule updates
|
|
which were added for each submodule in step 4 above to the 7.0 branch
|
|
(don't push). After committing, make sure that the output from
|
|
<tt>git submodule status --cached</tt> only shows the appropriate
|
|
version tags in the right-most parenthesized column with no
|
|
<tt>-<i>n</t>-g<i>xxxxxxx</i></tt> suffix.</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Release Manager</td>
|
|
|
|
<td>
|
|
<p><tt>git grep UNRELEASED</tt> and insert the release version to any
|
|
doxygen annotations that have a <tt>@since UNRELEASED</tt> comment.
|
|
Commit (don't push).</p>
|
|
<p>Edit the main EPICS Base version file and the built-in module version
|
|
files:</p>
|
|
<ul>
|
|
<li><tt>configure/CONFIG_BASE_VERSION</tt></li>
|
|
<li><tt>configure/CONFIG_LIBCOM_VERSION</tt></li>
|
|
<li><tt>configure/CONFIG_CA_VERSION</tt></li>
|
|
<li><tt>configure/CONFIG_DATABASE_VERSION</tt></li>
|
|
</ul>
|
|
<p>Version numbers should be set according to the level of changes made
|
|
since the last release. Note that the <tt>MAINTENANCE_VERSION</tt> or
|
|
<tt>PATCH_LEVEL</tt> value should have been incremented after the
|
|
previous release tag was applied. Set all <tt>DEVELOPMENT_FLAG</tt>
|
|
values to 0 and <tt>EPICS_DEV_SNAPSHOT</tt> to the empty string.</p>
|
|
<p>Edit the headings in the Release Notes to show the appropriate
|
|
version number and remove the warning about this being an unreleased
|
|
version of EPICS.</p>
|
|
<p>Commit these changes (don't push).</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Release Manager</td>
|
|
<td>Tag the epics-base module in Git:
|
|
<blockquote><tt>
|
|
cd base-7.0<br />
|
|
git tag -m 'ANJ: Tagged for release' R7.0.8.2
|
|
</tt></blockquote>
|
|
<p>Don't push to GitHub yet.</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Release Manager</td>
|
|
<td>Edit the main EPICS Base version file and the built-in module version
|
|
files:
|
|
<ul>
|
|
<li><tt>configure/CONFIG_BASE_VERSION</tt></li>
|
|
<li><tt>configure/CONFIG_LIBCOM_VERSION</tt></li>
|
|
<li><tt>configure/CONFIG_CA_VERSION</tt></li>
|
|
<li><tt>configure/CONFIG_DATABASE_VERSION</tt></li>
|
|
</ul>
|
|
<p>Version numbers should be set for the next expected patch/maintenance
|
|
release by incrementing the MAINTENANCE_VERSION or PATCH_LEVEL value
|
|
in each file. Set all <tt>DEVELOPMENT_FLAG</tt> values to 1 and
|
|
<tt>EPICS_DEV_SNAPSHOT</tt> to "-DEV".</p>
|
|
<p>Set up the headings in the Release Notes for the next release
|
|
version number and restore the warning about this being an unreleased
|
|
version of EPICS.</p>
|
|
<p>Commit these changes (don't push).</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Release Manager</td>
|
|
<td>Export the tagged version into a tarfile. The <tt>make-tar.sh</tt>
|
|
script generates a gzipped tarfile directly from the tag, excluding the
|
|
files and directories that are only used for continuous integration:
|
|
<blockquote><tt>
|
|
cd base-7.0<br />
|
|
./.tools/make-tar.sh R7.0.8.2 ../base-7.0.8.2.tar.gz base-7.0.8.2/
|
|
</tt></blockquote>
|
|
Create a GPG signature file of the tarfile as follows:
|
|
<blockquote><tt>
|
|
cd ..<br />
|
|
gpg --armor --sign --detach-sig base-7.0.8.2.tar.gz
|
|
</tt></blockquote>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Release Manager</td>
|
|
<td>Test the tar file by extracting its contents and building it on at
|
|
least one supported platform. If this succeeds the commits and new git
|
|
tag can be pushed to the GitHub repository's 7.0 branch (assumed to be
|
|
the <tt>upstream</tt> remote):
|
|
<blockquote><tt>
|
|
git push --follow-tags upstream 7.0
|
|
</tt></blockquote>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="3">Publish to epics.anl.gov</th>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Website Editor</td>
|
|
<td>Copy the tarfile and its signature to the Base download area of the
|
|
website.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Website Editor</td>
|
|
<td>Update the website subdirectory that holds the release
|
|
documentation, and copy in the files from the base/documentation
|
|
directory of the tarfile.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Website Editor</td>
|
|
<td>Update the webpage for the new release with links to the release
|
|
documents and tar file.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Website Editor</td>
|
|
<td>Add the new release tar file to the website Base download index
|
|
page.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Website Editor</td>
|
|
<td>Link to the release webpage from other relevent areas of the
|
|
website - update front page and sidebars.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Website Editor</td>
|
|
<td>Add an entry to the website News page, linking to the new version
|
|
webpage.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th colspan="3">Publish to epics-controls.org</th>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Website Editor</td>
|
|
<td>Upload the tar file and its <tt>.asc</tt> signature file to the
|
|
epics-controls web-server.
|
|
<blockquote><tt>
|
|
scp base-7.0.8.2.tar.gz base-7.0.8.2.tar.gz.asc epics-controls:download/base<br />
|
|
</tt></blockquote>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Website Editor</td>
|
|
<td>Follow instructions on
|
|
<a href="https://epics-controls.org/resources-and-support/documents/epics-website-documentation/adding-a-page-for-a-new-release/">
|
|
Add a page for a new release</a> to create a new release webpage (not
|
|
required for a patch release, just edit the existing page). Update the
|
|
TablePress "Point Releases" table and add the new download, and adjust
|
|
the XYZ Html Snippet for the series download.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th colspan="3">Publish to GitHub</th>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Release Manager</td>
|
|
<td>Go to the GitHub
|
|
<a href="https://github.com/epics-base/epics-base/releases/new?tag=R7.0.8.2">
|
|
Create release from tag R7.0.8.2</a> page.
|
|
Upload the tar file and its <tt>.asc</tt> signature file to the new
|
|
GitHub release page.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Release Manager</td>
|
|
<td>We used to close out bug reports in Launchpad at release-time, this
|
|
would be the time to do that if we have an equivalent on GitHub.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th colspan="3">Make Announcement</th>
|
|
</tr>
|
|
<tr>
|
|
<td><input type="checkbox"></td>
|
|
<td>Release Manager</td>
|
|
<td>Announce the release on the tech-talk mailing list.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</form>
|
|
</body>
|
|
</html>
|