Instructions for releasing a new version of Bowtie 2
====================================================

Author: Ben Langmead (langmea@cs.jhu.edu)
Date: 12/21/2012

Prerequisites:
- Need a way of building Linux binaries.  It's recommended that you not build
  on a Linux 3.X distro (for portability reasons)
- Need a way of building binaries for Mac OS X.
- Need a way of building Windows binaries, both 32-bit and 64-bit.
- Need "pandoc" installed on at least one of those machines.
- Need access to the GitHub repository.
- Need a sourceforge account with the appropriate permissions.
- TBB is now the default threading library and should be installed
  either from source or using a package manager

 1. Check that the code compiles with no issues, including with very recent
    versions of g++, and with clang on a Mac.
    - To use clang on the Mac: "make CPP=clang++ allall"

 2. Check that all the simple tests pass: "make simple-test"

 3. Check that random tests pass: "make random-test"

 4. Check that performance, sensitivity and accuracy are not substantially
    changed.
    - TODO!  Need infrastructure for this.

 5. Update BOWTIE2_VERSION with new version number if this hasn't already been done.

 6. Update NEWS and doc/website/recent_news.ssi if this hasn't already been
    done. (And even if it has, make sure the release date mentioned in those
    documents is correct.)
    - In both cases, add a section at the top describing the new release, along
      with bullet points describing improvements and changes in that release.
    - For recent_news.ssi, hyperlink concepts or command-line options so that
      they point into the manual.
    - Make sure to update the version numbers mentioned in the paragraph at the
      beginning of the NEWS file.
    - Potentially move an entry or two from the bottom of
      doc/website/recent_news.ssi to the top of doc/website/old_news.ssi if it
      gets too long.

 7. Update the text and html version of the manual, which are derived from the
    source MANUAL.markdown file.
    - In Bowtie 2 root directory, do "make doc" (you'll have to have 'pandoc'
      installed).  The output will be stored both in MANUAL and
      doc/manual.html.
    - In doc/manual.html, highlight and copy everything from <div id="TOC">
      down to but not including </body>.  Then paste it in the corresponding
      part of doc/website/manual.ssi.
    - Update the version number at the top of doc/website/manual.ssi.

 8. Go to the sourceforge site for the Bowtie 2 files:
    https://sourceforge.net/projects/bowtie-bio/files/bowtie2/
    And make a new directory (with "Add Folder" button) for the new version. 

 9. Update doc/website/rhsidebar.ssi to refer to the new version in the section
    immediately following "<h2>Latest Release</h2>"

10. Commit all changes due to the steps taken so far.

11. Upload updated webpages
   - In doc/website directory, do "sh push.sh"

12. Make Bowtie 2 source archive:
   - From the Bowtie 2 git root, run "make bowtie2-src"
   - Upload to sourceforge:
     scp bowtie2-X.Y.Z-source.zip USERNAME@frs.sourceforge.net:/home/frs/project/bowtie-bio/bowtie2/X.Y.Z/
     (But replace X.Y.Z and USERNAME with appropriate values)

13. Make Bowtie 2 Linux 64-bit binaries.
   - On a Linux machine (e.g. igmX), from the Bowtie 2 git root run "make clean"
   - Then "make bowtie2-pkg".  (Use "make -j12" or similar to use many
     CPUs at once).
   - Rename the resulting archive to match the typical naming scheme.  E.g.:
     "mv bowtie2-X.Y.Z.zip bowtie2-X.Y.Z-linux-x86_64.zip"
   - Upload to sourceforge:
     scp bowtie2-X.Y.Z-linux-x86_64.zip USERNAME@frs.sourceforge.net:/home/frs/project/bowtie-bio/bowtie2/X.Y.Z/
     (But replace X.Y.Z and USERNAME with appropriate values)
   - Repeat from the beginning adding the NO_TBB=1 flag to the second step to create the legacy packages

14. Make Bowtie 2 Mac OS X 64-bit binaries.
   - From the Bowtie 2 git root run "make clean"
   - Then "make EXTRA_FLAGS=-mmacosx-version-min=10.5 bowtie2-pkg".
     (Use "make -j12" or similar to use many CPUs at once).  The -mmacosx...
	 flag forces the binaries to be backward compatible with Mac OS version
	 10.5 and up.
   - Rename the resulting archive to match the typical naming scheme.  E.g.:
     "mv bowtie2-X.Y.Z.zip bowtie2-X.Y.Z-macos-x86_64.zip"
   - Upload to sourceforge:
     scp bowtie2-X.Y.Z-macos-x86_64.zip USERNAME@frs.sourceforge.net:/home/frs/project/bowtie-bio/bowtie2/X.Y.Z/
     (But replace X.Y.Z and USERNAME with appropriate values)
   - Repeat from the beginning adding the NO_TBB=1 flag to the second step to create the legacy packages

15. Make Windows 64-bit binaries
    Prerequisites
    -------------
    By default MinGW can only compile 32 bit binaries, so MinGW-w64 will be needed for 64 bit binaries
    MinGW installer - https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download
    MinGW64 - https://sourceforge.net/projects/tdm-gcc/files/latest/download
    TBB - https://www.threadingbuildingblocks.org/sites/default/files/software_releases/source/tbb2017_20161128oss_src.tgz

   - Download and run the mingw-get-setup installer and set the install directory to C:\MinGW\32
   - When presented with the "MinGW Installation Manager" window click on "All Packages" and mark the msys-zip, msys-unzip, and msys-wget packages for installation.
   - Download and run the mingw-w64-install installer and set the install directory to C:\MinGW\64
   - Once all MinGW packages are installed open Windows Explorer and navigate to C:\MinGW\msys\1.0 and run the msys.bat file to start the MinGW shell.
   - To build TBB from source
       * wget --no-check-certificate <tbb url>
       * tar -xzf <tbb_archive_name>.tgz
       * cd into the TBB source directory
       * run mingw32-make.exe compiler=gcc arch=intel64 runtime=mingw
   - Upon successful compilation there should now exist a build directory which contains the dlls needed by the linker. Before building bowtie make sure that the following environment variables contain the path to the TBB headers and dlls respectfully. From the root of the TBB directory run:
       * export CPATH=$CPATH:`pwd`/include
       * export LIBRARY_PATH=$LIBRARY_PATH:`pwd`/build/windows_intel64_gcc_mingw_release
       * the changes to the above environment variables will only available for the duration of the current shell session. To make them permanent make sure they are added to the ~/.profile file or your preferred shell’s rc file e.g. ~/.bashrc.

   - From the MinGW shell cd to the Bowtie 2 git root run "make clean"
   - Then "make bowtie2-pkg".  (Use "make -j12" or similar to use many
     CPUs at once).
   - Rename the resulting archive to match the typical naming scheme.  E.g.:
     "mv bowtie2-X.Y.Z.zip bowtie2-X.Y.Z-mingw-x86_64.zip"
   - Upload to sourceforge:
     scp bowtie2-X.Y.Z-linux-x86_64.zip USERNAME@frs.sourceforge.net:/home/frs/project/bowtie-bio/bowtie2/X.Y.Z/
     (But replace X.Y.Z and USERNAME with appropriate values)
   - Repeat the above 4 steps adding the NO_TBB=1 flag to the second step to create the legacy packages

16. Make a git annotated tag for the new version using "git tag -a"
   - See: http://git-scm.com/book/en/Git-Basics-Tagging
   - Basically, do something like:
     + git tag -a v2.0.5 -m 'Just prior to 2.0.5 release on 1/4/2013'
     + git push origin --tags

17. Update the sourceforge "Looking for the latest version?" pointers:
   - Go to: https://sourceforge.net/projects/bowtie-bio/files/bowtie2/X.Y.Z
   - Click the "i" ("info") button next to the Mac OS X 64-bit archive.  Check
     the Mac os "Default Download For:" checkbox and save.
   - Do same for Linux 64-bit archive and the Linux checkbox.
   - Do same for Windows.
   - Click the "i" ("info") button next to the source archive.  Check all the
     "Default Download For:" checkboxes not checked so far and save.

18. Upload the release binaries to github release area as well. 
   - Go to the releases area and click 'Edit' button for the current release.
   - Change the release description so it will include the NEWS.
   - Upload the tgz archives for current release.

19. Send an email to bowtie-bio-announce@lists.sourceforge.net announcing the
    release.
   - Subject: "Bowtie 2 X.Y.Z released"
   - Body: Basically a copy and paste of the release notes for the most recent
     release from the NEWS file.
