Release Checklist

Here is information about the various steps required to produce a new release of BioCocoa; over time when the process has been worked out then these will get coded into distribution scripts to automate much of the process.

The overall release tasks include:

Create release branch/tags in the SVN repository.
Create source/binary distribution files.
Update web pages, post announcements.

To avoid cluttering up the main check list with extra details, look to the bottom of this page for issues, workarounds, FAQs, etc.

SVN Repository Tasks

One of the primary features of using a source code repository is its ability to support software releases and maintain identity of a specific release. Branching allows the release to be worked on concurrently with development for the next release as well as bug fixing independent of the main development; while tagging allows historical access to the exact files in a release.

The repository tasks are slightly different for a bug fix release versus a release with new functionality.

SVN Repository Tasks for New Functionality Release

Checkout BioCocoa from the repository. You can use an existing checkout but make sure you don't have any modified files, etc. Safer to just start from a clean checkout.
```
svn checkout svn+ssh://user@bioinformatics.org/svnroot/BioCocoa
```
Update the version number in the VERSION file in trunk and commit to the repository. If the major version is incrementing then the framework version in the Xcode project and makefiles also needs to increment.
Update the Readme.txt with the new version number, add some bullet items about what the new release.
Make a branch for the release by copying trunk to a directory in the branches directory and commit the new branch.
```
svn copy trunk branches/X.Y-release
svn commit -m "X.Y-release branch"
```
Now do all release work in the branch. Any modifications to scripts, etc. are done in the branch. Those changes will be merged back to the main development branch later.

SVN Repository Tasks for Bug Fix Release

Currently bug fix releases should be rare as we don't have a large user and developer community. Consider whether waiting for the next new functionality release is sufficient.

Bug fix release do not involve creating a new branch. Instead work in the appropriate branch directory, code and test the bug fixes there.

Update the version number in the VERSION file in trunk and commit to the repository, this should just be incrementing the bug version number.
Now do all release work in the branch. Bug fixes and any other modifications will be merged back to the main development branch later.

Distribution File Tasks

When creating distribution files, we want to eliminate all of the extra files and directories that exist in a repository checkout; we do this by using the export command to get a local copy of the release files.

Create the source code release

Export the source code from the release branch, make sure to use the correct Z value for the bug version number.
```
svn export
svn+ssh://user@bioinformatics.org/svnroot/BioCocoa/BioCocoa
/branches/X.Y-release biococoa-X.Y.Z
```
Archive the exported code directory, that's the source code release!
```
tar zcvf biococoa-X.Y.Z-src.tgz biococoa-X.Y.Z
```
Test the source code release by extracting the files into a new directory, preferably on a clean machine, and verify that you compile it.

Create the binary release (Mac OSX)

Extract the source code from the release file created above.
Compile with Xcode using the Release target for BioCocoa.framework and BioCocoa Documentation.
Create a temporary directory. We are going to gather all of the release files together.
Using the Finder, copy the following to the temporary directory
- BioCocoa.framework from the Release build directory.
- Documentation directory.
- license.txt file.
- Readme.txt file.
Use Get Info from the Finder on the temporary directory to calculate the total size of the release.
Open Disk Utility and create a read/write disk image with a size large enough to hold all the release files. Use Mac OS Extended file system with journaling, journaling uses up space that isn't needed. Change the Volume Name from Disk Image to BioCocoa, do this now because it cannot be changed later.
Open the disk image in Finder, we will construct the release image.
- Switch the disk image folder to Icon view.
- Use Show View Options and set the background image to Documentation/images/BCBanner.jpg also select "Always open in icon view".
- Click the upper right window button to eliminate the left tree view panel and resize the window so it exactly fits the background image.
- Copy all the release files to the disk image, rearrange so that they are nicely placed under the BioCocoa image. Look at an existing release disk image for an example.
Now use Disk Utility to convert the disk image to a compressed disk image. Name the image BioCocoa-X.Y.Z.

Move the release files to the download directory.

The distribution files now get put on bioinformatics.org.

Transfer biococoa-X.Y.Z-src.tgz and BioCocoa-X.Y.Z.dmg to your account on bioinformatics.org using sftp.
ssh into bioinformatics.org
Change to the biococoa group (newgrp biococoa).
Change your permission mask to group write (umask 0002).
Copy biococoa-X.Y.Z-src.tgz and BioCocoa-X.Y.Z.dmg to /memberroot/peterschols/public_html/biococoa/downloads
Copy documentation to web.
- tar up and sftp the built Documentation directory to bioinformatics.org
- Create a X.Y.Z directory under /memberroot/peterschols/public_html/biococoa/Documentation
- Untar the documentation into the directory.
Should also copy the source release to the BioCocoa project page on bioinformatics.org.
```
http://www.bioinformatics.org/project/?group_id=318
```
Login with your account, goto the BioCocoa project, select File Release under the Group Admin options and follow the directions. Cut/paste the release information from Readme.txt as the release notes; check the box so that its displayed as text instead of HTML.
Unfortunately, bioinformatics.org doesn't recognize the dmg extension, so you need to compress it which will give it a zip extension.

Announcement Tasks

Update BioCocoa to point to new release as current.
Email announcement file to mailing list.

Issues, Workarounds, Helpful Hints

Here are a set of topics that elaborate on various details of making a release.

Versioning Scheme

BioCocoa sticks to the standard versioning scheme used by many GNU/Linux software packages, the X.Y.Z scheme where X, Y and Z are integers. X is the major version and increments with a significant change in the API, possibly breaking backward compatibility. Y is the minor version and increments with each release that introduces new functionality. Z is the bug version and increments with bug fix releases.