Notes on building tarballs and uploading releases

(Details of htslib.org updates to follow.)

Author: jmarshall

RELEASE.md

@@ -31,11 +31,11 @@ And finally commit it:
 
 ## Tag release commit
 
-Tag this merge commit, using "HTSlib [patch] release X.Y.Z: summary" etc as the subject line and the release notes copied from _NEWS_ as the body of the commit message.  You want to use an annotated (`-a`) or ideally signed (`-s`) tag:
+Tag this merge commit, using "HTSlib [patch] release X.Y.Z: summary" etc as the subject line and the release notes copied from _NEWS_ as the body of the tag message.  You want to use an annotated (`-a`) or ideally signed (`-s`) tag:
 
     git tag -s VERSION
 
-Keep the first (subject) line of the commit message short, so that `git tag -n` displays well in a standard-width terminal.  You have 63 characters.
+Keep the first (subject) line of the message short, so that `git tag -n` displays well in a standard-width terminal.  You have 63 characters.
 
 If you are signing the tag, you may wish to prepare the message in a file and use `git tag -F msg.txt --cleanup=verbatim` so that you can preserve a trailing blank line at the end of the file to separate the `-----BEGIN PGP SIGNATURE-----` line from the release notes.
 
@@ -66,8 +66,69 @@ And finally commit it to **develop**:
 
 This repository's _Makefile_ contains recipes to build release tarballs from Git repositories alongside this directory, i.e., it expects to find appropriate repositories in _../htslib_, _../samtools_, and _../bcftools_.
 
+You can build tarballs of all three projects with
+
+    make tar TAG=1.x
+
+where the value supplied for `TAG` is really any commit-ish, but usually a tag.  This creates _htslib-\<tag\>.tar.bz2_ etc; the _samtools_/_bcftools_ tarballs contain their own copy of HTSlib and their _Makefile_ is adjusted to point to it.  _Aclocal_, _autoheader_, and _autoconf_ are run as appropriate before the tarballs are created.
+
+Almost always the versions for SAMtools/BCFtools and the embedded HTSlib will be the same.  But if you need to inject a different version of HTSlib append `HTSTAG=1.y` to the command line above.
+
+Test these tarballs by unpacking them and doing a trial build and `make test`.  You may also wish to diff a `tar tvf` listing with a listing of the previous release of each package, and ensure that all file additions and removals can be explained.
+
+If you want to make a tarball of only one project, use
+
+    make TAG=1.x samtools-1.x.tar.bz2
+
+(It might be worthwhile altering the scripts and _Makefile_ so that `$(TAG)` can be derived from specified filenames, rather than repeating yourself.)
+
 
 # Uploading to GitHub and SourceForge
 
+We currently upload tarballs and release notes to both GitHub and SourceForge.  It is a fairly lengthy process.
+
+1. Using the [web interface], create a new `1.x` subdirectory and mark it as "staged".
+
+2. Using [scp or sftp], upload the release tarballs to SourceForge:
+
+        $ sftp [email protected]
+        sftp> cd /home/frs/project/samtools/samtools/1.x
+        sftp> put *-1.x.tar.bz2
+
+    It will take some time before these files are replicated to the various mirrors.
+
+3. Prepare the updates for [htslib.org].
+
+    Also prepare the announcement email and tweets.
+
+4. On the **Releases** page of each of the GitHub repositories to be released, use the "Draft a new release" button.  Leave the "Tag version" blank for now, as the tags have not yet been pushed to GitHub.  For now, fill in the release notes by copying from _NEWS_ and markdownifying the text, and attach the release tarball.  Add the following boilerplate to the bottom of the release notes:
+
+        ---
+
+        _The **[foo-1.x].tar.bz2** download is the full source code release. The “Source code” downloads are generated by GitHub and are incomplete as they [don't bundle HTSlib and] are missing some generated files._
+
+    For now, save this as a draft.
+
+5. Push your branch updates and new tags:
+
+        git push origin master develop 1.x
+
+    As soon as you push the tags, people are likely to notice and start tweeting about it(!), so you may wish to do the next steps fairly quickly.
+
+6. Make the GitHub releases live: fill in the "Tag version" now that the tag exists on GitHub, check that the right tarball is attached to the right repository, and **publish** the release.
+
+7. Push the website updates.
+
+8. Concatenate the three sets of markdownified release notes as _README.md_ and upload it to SourceForge (likely via the [web interface]).
+
+9. By now, the SourceForge files may have populated enough mirrors that you can locate your **samtools-1.x.tar.bz2** file in the [web interface] and select it (via the **(i)** button) as the default download.  Also unstage the directory.
+
+10. Send the release announcement email (to `samtools-announce`, CCed to `-devel` and `-help`, with reply-to set to `-help`) and tweet from [@htslib].
+
+[web interface]: https://sourceforge.net/projects/samtools/files/samtools/
+[scp or sftp]: https://sourceforge.net/p/forge/documentation/Shell%20Services/
+[htslib.org]: http://www.htslib.org/
+[@htslib]: https://twitter.com/htslib
+
 
 <!-- vim:set linebreak: -->