pages tagged pgpyakkinghttp://yakking.branchable.com/tags/pgp/yakkingikiwiki2015-09-23T11:00:13ZOn making releaseshttp://yakking.branchable.com/posts/releases/Lars Wirzenius2015-09-23T11:00:13Z2015-09-23T11:00:06Z
<p>Any software project with users other than the developers should make
releases.</p>
<ul>
<li><p>A release is the developers saying that the software is in a good
shape and ready to be used. This is important for the users, since
otherwise they would have to try various version control revisions
to find something that looks like it might work. Linux distributions
and others who package software want releases for the same reason.</p></li>
<li><p>Sysadmins want releases for an additional reason: they want to be
able to reproduce an installation, so that they can have many
identical machines.</p></li>
<li><p>Releases are important for the developers themselves as well.
Without releases, it becomes harder to support users, since the
first support step is to determine the version the user is running,
and that becomes harder if it might be any commit from any branch in
the history of the project.</p></li>
</ul>
<p>Given that releases are useful, what's a good way to make them? A
popular opinion today is that a release is made by <a href="https://en.wikipedia.org/wiki/Revision_tag">tagging</a> a commit in
a version control repository. This is the minimum for what constitutes
a release, and it's fine for many people. Your author is more picky.</p>
<p>For a proper release, the following is a reasonable checklist:</p>
<ul>
<li>A tag in version control (in <a href="http://git-scm.com/">git</a>, it should be <a href="https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work">OpenPGP signed</a>).</li>
<li>A release tar archive, compressed using a suitable compression tool.
<ul>
<li>The archive may contain more files than are in the tagged
version control commit. For example, autoconf-generated files
for configuring a build.</li>
</ul>
</li>
<li>A <a href="https://www.gnupg.org/gph/en/manual/x135.html#AEN160">detached OpenPGP signature</a> of the compressed tar archive.</li>
</ul>
<p>An actual tar archive is necessary because it may not be possible to
reproduce the release tar archive at a later date. For example, the
way git produce a tar archive may change, and the compression tool may
also change.</p>
<p>This even has security implications: it is plausible that an attack
could happen by exploiting a flaw in the decompression software, if
the attacker can use any compression program. If a release is made,
and the release artifacts (tar archive, detached signature) are
verified and tested, it gets much harder to construct an attack.</p>
<hr />
<p>A short checklist for making a release:</p>
<ul>
<li>Ensure the software is in a fit state to be released. It should work
correctly; documentation, translations, and release notes should be
up to date; and so on.</li>
<li>In particular, ensure the desired version number is correct and consistently
applied across the software.</li>
<li>Sign the release tag.</li>
<li>Produce the release tar archive (compressed), including any
generated files it should contain.</li>
<li>Produce the detached signature for the tar archive.</li>
<li>Produce any other release artifacts.</li>
<li>Test the release artifacts in some suitable way.</li>
<li>Publish the release artifacts and push the signed tag.</li>
<li>Announce the release in a suitable way: on the project website,
blog, mailing list, or using a message in a bottle, depending on the
project.</li>
<li>Figure out a way to automate as much as possible of this so it's
easier to do the next time.</li>
</ul>
<p><em>For most projects, making a release should happen often enough that it
pays off to automate most of the process.</em></p>