Making a BioPerl release
Give people a good head's up about the release schedule so they can be sure to check in their code. Remind people to add themselves to the AUTHORS file so they get credit for contributing to the release.
A Release candidate, or RC, is a dry run of sorts to work out any quirks in the current code before unleasing it upon the world. Remember, the current BioPerl attitude is to be conservative, we would rather have a release be late than have a lot of stupid bugs in it. Given that, it is impossible to release completely bug-free code, and it is impossible for code to remain bug-free. Therefore we must maintain a balance between fixing bugs we have located vs. determining how much they will affect the next slated release.
Other authors prefer an 'alpha' release style, where some minor updates and bug fixes could be incorporated between an alpha release (designated with an additional underscore and alpha number). The key difference between the two styles is the final release with an alpha style release schedule may differ slightly from the actual release itself, whereas normally using release candidates the last RC is virtually unchanged from the actual release barring the change in version number.
Traditionally the BioPerl developers have followed a RC schedule. However, these are still tagged with alpha-like numbering, therefore we leave it up to the release pumpkin to decide which style best works for them. As long as the proper tags are made then this usually isn't a problem.
We are following a typical point release schedule following the BioPerl 1.6.900 (aka 1.6.9) release, primarily to deal with bug fixes. There were well over 50 documented bug fixes between the 1.6.1 and 1.6.9 releases (a period which spans the transition from our old Subversion repository to our new GitHub location) . B/c we are simplifying the 'build' process (whittling down BioPerl-specific issues via Bio::Root::Build) and due to our migration over to git/GitHub, we will hopefully make future releases much less painful.
Creating a tagged release
Previous releases from Subversion created a release branch, primarily b/c there is very little (any?) difference between branches and tags with Subversion. One could create a release branch via git, but there isn't any point to doing so unless the code is intended to be a fork of stable code (away from the master branch, such as for the original 1.6 release branch) that will only incorporate bug fixes.
To create a tag, just use:
git tag -a release-1-x-y
will generate a tag for a specific release and open your default editor for adding additional annotation (a nice plus with git). This should then be pushed up to the origin:
git push --tags
Checking out tagged code
As releases are tagged (no longer separate branches), one can do the following:
git checkout release-1-x-y
to get the release-1-x-y release. Pretty simple.
Note about bug fixes and versioning
We may switch to a different mechanism for reporting these, but in the meantime we still report significant bug fixes in the 'Changes' file. However, due mainly to the volume of bug reports we get and bad habits we have perpetuated over the years, we unfortunately tend to forget to update the 'Changes' file until the last minute (hey, at least we're getting better at adding tests for bug fixes).
So, these things need to be addressed PRIOR to tagging a release:
- Add significant code mods to 'Changes'
- Update all VERSIONs
- Check README and INSTALL for needed updates
Merging fixes over from the main trunk
If you are on a release branch, you would do:
git merge master
TODO: talk about 'rebase'
Packaging up a release candidate or alpha release
Before a BioPerl version can be officially be released it is important to have to have it tested and validated by as many people as possible in order to catch obvious bugs and errors.
We say obvious because you aren't at the release candidate stage unless most of the important bugs in a release have been been looked at. Hopefully these bugs will have gotten an entry in the bugzilla database. The Release pumpkin has the responsibility of defining the bugs and feature requests which are show stoppers for a release and which ones will be left for future releases.
Prepping code for a release
Here is a checklist of things that can often be overlooked:
- Version numbers: check that the version number is correct in the following files
- Makefile.PL and Build.PL (For Bioperl-run, Bioperl-db etc)
- Change log: make sure it is up-to-date. we formerly used maintenance/cvs2cl_by_file.pl (based on cvs2cl.pl) helpful in the process; we'll be switching to svn2cl
It is not necessary to make a tag in Subversion for a release candidate, but you can if you feel that sufficient progress will be made between release candidates to want to have access to the checkpoint. Tags can of course be removed at any point if they become irrelevant.
Making the distribution archives
The release candidate needs to be provided in archived files suitable for distribution. The MANIFEST, MANIFEST.SKIP, META.yml and Makefile.PL files should all be created just-in-time. From a clean export (or following ./Build realclean), do:
$ perl Build.PL $ ./Build dist
This creates appropriately named archives (.tar.gz, .tar.bz2, .zip). The .tar.gz filename is chosen to be CPAN-compatible (contains an underscore in the version to denote a developer release), working if Bio::Root::Version has an appropriate version number: 1.005002001 would mean RC1 of the developer release 1.5.2 and gets the name bioperl-1.5.2_001-RC.tar.gz; 1.005002100 (note the ending 100) would be used as the final release number, and gets the name bioperl-1.5.2_100.tar.gz; 1.005002101 would be a point release for bug fixes, getting the name bioperl-1.5.2_101.tar.gz; 1.006000001 would be RC1 of a release and gets the name bioperl-1.6.0_001-RC.tar.gz; 1.006000100 gets bioperl-126.96.36.199.tar.gz; 1.006001001 gets bioperl-188.8.131.52.tar.gz.
Test the CPAN distribution by uploading it to open-bio (see below) in an appropriate sub-directory of 'authors', then add to your CPAN urllist:
cpan>o conf urllist push ftp://ftp.open-bio.org/pub/bioperl/DIST/
You should also create the Windows PPM and PPD files:
$ ./Build ppmdist
Upload the resulting .tar.gz file and append the contents of the generated bioperl.ppd file into the package.xml file in the Bioperl repository, between the <REPOSITORY> tags. A fake (empty) Bundle .tar.gz will also have been created - upload this as well.
Making packages public
Copy the packages to the DIST directory in the bioperl html directory (/home/websites/bioperl.org/html/static/DIST).
If you do not have an account on the webserver (currently called portal.open-bio.org) contact one of the main developers and they will insure you get one via the helpdesk.
Update the SIGNATURES.md5 file:
md5sum * > SIGNATURES.md5
Make the distributions available on CPAN (ensure that $VERSION contains a _ to mark this as a developer release).
If you do not have a PAUSE account, request one. Then ask a previous pumpkin to grant you co-maintainer status for BIOPERLML when you have an account name.
Upload the .tar.gz version of the distribution to CPAN. Make sure that the filename contains the version number with an underscore to mark it as a developer release. For developer releases there will be no indexing, but for normal releases you should get a email with no problems. Wait 24 hours for it to truly finish everything it does. Now change permissions (choose option 2.1) so that BIOPERLML is primary owner of all modules (old modules will be BIOPERLML anyway, but any new modules you may have uploaded will belong to you only, so this step is necessary). Finally, choose Select Mailinglist/Action, then select 'share_perms' from the drop-down menu and choose option 3.1 to make the next pumpkin (or youself if you'll need to upload more versions) co-maintainer.
Making a release
If you are prepared to make the release (usually the Release pumpkin will have made this decision based on the number of bug reports and documentation errors that are found in the last RC), there are several steps that need to be followed, much like in making a release candidate.
Make the distrubution archives and upload just as when making a release candidate.
The default download links need to be updated (sym links to current_core_stable and current_core_unstable). The website needs to be updated to reflect the version number of the latest release.
Announce the release
- Post to news.open-bio.org and/or to the News server.
- Post to the mailing list.
- Update Freshmeat entry (Jason)
When posting an announcement to the mailing list include a summary of what has changed or been added since the last release. Highlight important bug fixes and include snippets of the Changes file.
Making Pdoc static
Steps for making Pdoc static dump for doc.bioperl.org
Additional support work
There are a couple more things that need to be done after a major release is produced.
Creating the branches
See Using Git for information. In general, there are two reasons to create a branch:
- Making a release branch (i.e. for 1.5.2 release, create the 1.5.2 branch)
- Testing out a new feature (or refactoring an old one)
For release branches, we follow the rule of making the branch first, testing it out, then creating a tagged release for specific releases and release candidates AFTER we check the release. Feature branches, on the other hand, may never be tagged (they are generally merged back into trunk at some point). These branches are typically deleted after merging back to trunk.
Update the SRC FTP dir
We provide a plain checkout code for browsing in addition to the Git interface. This lives on the FTP server and webserver in the SRC directory (html/SRC). Another dir for a branch should be created in the same way there are currently ones for the 1.4 branch.