How to build a release for Biopython.

Build Biopython in 22 easy steps!!

Setup required for a new release manager

The instructions below require that you have access to a few servers and the code repository. When you start, be sure to have write access to:

If you don’t have any of the above, please ask.

The instructions proper

These instructions are for a Unix machine, with a Windows machine also needed to test and prepare the Windows installers.

make sure I have the latest code:
```
$ git pull origin master
```
make sure the README.rst file is still up to date
add any important info to NEWS.rst or DEPRECATED.rst - you can get a log of recent git changes like this (adjust the date accordingly):
```
$ git log --since="2016/01/01" --reverse --pretty="medium"
```
make sure CONTRIB.rst still current
make sure setup.py and MANIFEST.in are still up to date
- Are there any new modules/files which should get installed?
bump version numbers and set the release data:
- Biopython version - edit Bio/__init__.py
- Biopython Tutorial - update the date/version line in the Doc/Tutorial.tex file
- Biopython NEWS.rst - fill in the release date
- Make sure to commit the modified files to github, e.g.
```
$ git commit Bio/__init__.py Doc/Tutorial.tex NEWS.rst -m "Call this Biopython 1.68"
```

do last check to make sure things are checked in:

$ rm -r build
$ rm Tests/*.pyc
$ make clean -C Doc
$ git status

build Biopython and do last regression test:
```
drevil:~biopython> python setup.py build
drevil:~biopython> python setup.py test
```
Ideally do this with a clean checkout on your Windows machine too. Assuming you have setup your compilers etc appropriately just do this:
```
C:\python27\python setup.py build
C:\python27\python setup.py test

C:\python33\python setup.py build
C:\python33\python setup.py test

C:\python34\python setup.py build
C:\python34\python setup.py test
```
If you are using MinGW, do not forget to add --compiler=mingw32 (or make it the default on distutils, see the step on building on Windows machines). Also If you are using a modern MinGW compiler, then distutils of Python will use an option (-mno-cywgin) that is deprecated and will break gcc. A possible solution is to edit distutils, but on recent Python (3.3 as tested) this seems to have been addressed.

Running the tests simultaneously is risky, as two threads may both try to read/write to the same temp files.

check out clean version somewhere else:

drevil:~tmp1/> git clone git://github.com/biopython/biopython.git
drevil:~tmp1/> cd biopython

make documentation PDF, text and HTML files in Doc:

drevil:~tmp1/biopython/> make -C Doc
drevil:~tmp1/biopython/> make clean -C Doc

make the source distribution

drevil:~tmp1/biopython> python setup.py sdist --formats=gztar,zip

untar the file somewhere else

drevil:~tmp1/biopython/> cd ..
drevil:~tmp1/> tar -xzvf biopython/dist/biopython-1.68.tar.gz
drevil:~tmp1/> cd biopython-1.68

Check to make sure it includes the HTML and PDF files under Doc

make sure I can build and test it

drevil:~tmp1/biopython-1.68/> python setup.py build
drevil:~tmp1/biopython-1.68/> python setup.py test
drevil:~tmp1/biopython-1.68/> python setup.py install --prefix /tmp/test-install

A typical source of failure here (on the tests) is the lack of example files being added to the source distribution: add them to MANIFEST.in

Update API documentation using Epydoc (this can often report otherwise overlooked errors).

If you haven’t already, clone the DIST repository - otherwise first fetch any upstream changes.

$ cd ~/repositories
$ git clone git@github.com:biopython/DIST.git
$ cd ~/repositories/DIST

Remove version of the API documentation which we’re going to replace:

$ git rm docs/api/*

Go to the /tmp/test-install/lib/python2.7/site-packages directory. This is the directory created under your source installation after the install step above. Running epydoc in your git tree works, but can miss some packages due to import errors.

$ cd /tmp/test-install/lib/python2.7/site-packages
$ grep "__version__" Bio/__init__.py
__version__ = "1.68"
$ epydoc -v -o ~/repositories/DIST/docs/api/ -u http://biopython.org -n Biopython --docformat restructuredtext Bio BioSQL
$ grep "__version__" ~/repositories/DIST/docs/api/Bio-pysrc.html
<a name="L13"></a><tt class="py-lineno"> 13</tt>  <tt class="py-line"><tt class="py-name">__version__</tt> <tt class="py-op">=</tt> <tt class="py-string">"1.68"</tt> </tt>

Assuming no mismatches in version number (which would suggest epydoc is not looking at the new test installation), commit these new HTML files to the gh-pages branch:

$ cd ~/repositories/DIST
$ git add docs/api/*
$ git commit -m "epydoc for Biopython 1.68"

Update the tutorial too:

$ cd ~/repositories/DIST/docs/tutorial/
$ cp .../tmp1/biopython/Doc/Tutorial.html .
$ cp .../tmp1/biopython/Doc/Tutorial.pdf .
$ git commit Tutorial.html Tutorial.pdf -m "Tutorial for Biopython 1.68"

Push this to GitHub Pages to update the website:

$ git push origin gh-pages

Check this is live at http://biopython.org/DIST/docs/api/Bio-module.html, http://biopython.org/DIST/docs/tutorial/Tutorial.html, and http://biopython.org/DIST/docs/tutorial/Tutorial.pdf

Back in the main repository, tag the release:

$ cd  .../tmp1/biopython/
$ git tag biopython-168
$ git push origin master --tags

On your windows machine, build the Windows installers (either from a clean checkout, or an unzipped copy of the source code bundle made earlier). Build the installers first, if you do a build/test/install before hand you seem to get a bloated setup exe. Assuming you have setup your compilers etc appropriately just do this:
```
C:\python27\python setup.py bdist_wininst
C:\python33\python setup.py bdist_wininst
C:\python34\python setup.py bdist_wininst
C:\python35\python setup.py bdist_wininst
C:\python36\python setup.py bdist_wininst
```
and:
```
C:\python27\python setup.py bdist_msi
C:\python33\python setup.py bdist_msi
C:\python34\python setup.py bdist_msi
C:\python35\python setup.py bdist_msi
C:\python36\python setup.py bdist_msi
```
If you are using MinGW, you will have to make distutils use it (it will use a MS compiler by default). Here (contrary to the build step) you cannot pass the compiler as a parameter. The best solution might be to configure distutils
Remove any prior Biopython installations on your windows machine, and confirm the Windows installers work. Then copy them to your Linux machine.

Upload the new release to the website via GitHub Pages DIST repository.

$ cp dist/biopython-1.68.* ~/repositories/DIST/
# Also copy in the Windows files
$ cd ~/repositories/DIST/
$ git add biopython-1.68.*
$ git commit biopython-1.68.* -m "Downloads for Biopython 1.68"
$ shasum -a 256 biopython-1.68.*
$ md5sum biopython-1.68.*
$ git commit --amend # paste checksums into comment
$ git push origin gh-pages

Upload to the python package index (except for beta/alpha level releases):
```
$ cd  .../biopython/
$ pip install twine
$ twine upload dist/biopython-1.68.tar.gz
```
- You need to have a login on pypi and be registered with Biopython to be able to upload the new version
- Check this is live at https://pypi.python.org/pypi/biopython/
Update the website and announce the release:
- If you haven’t already, clone the biopython.github.io repository, (otherwise make sure your copy is up to date):
```
$ cd ~/repositories
$ git clone git@github.com:biopython/biopython.github.io.git
```
- Update the website:
```
$ cd ~/repositories/biopython.github.io
$ emacs _config.yml
$ emacs wiki/Biopython.md
$ emacs wiki/Download.md
$ git commit _config.yml wiki/Biopython.md wiki/Download.md -m "Biopython 1.68 released"
```
- before you announce the release, be sure to send your announcement text to the biopython-dev mailing list for proof-reading/final corrections.
- add to main page and downloads page (through the wiki), make sure the links work
- post the announcement on news.open-bio.org (which will update the news page and twitter via the news feed)
- add the new version to RedMine
- send email to biopython@biopython.org and biopython-announce@biopython.org (see mailing lists)
- forward the email to Linux packagers e.g. debian-med@lists.debian.org
Open an issue (or better a pull request) to update the Conda-Forge recipe via https://github.com/conda-forge/biopython-feedstock which populates https://anaconda.org/conda-forge/biopython
Bump version numbers again
- Update Bio/__init__.py version
- Biopython Tutorial - update the date/version line in the Doc/Tutorial.tex file
- Make sure to commit the modified files to github.
Include the suffix .dev0 to indicate this is a development version e.g. if you have __version__ = "1.68", make it 1.69.dev0