Making a BioPerl release
From BioPerl
Contents |
Making a release candidate
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.
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.
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.
Prepping code for a release
You will need to check out the code from CVS to make the release. See Using CVS for more help but basically it is as follows.
For a stable release you will likely be checking out the code from a branch that was put in before the release.
$ cvs -d:ext:YOURNAME@dev.open-bio.org:/home/repository/bioperl
Here is a checklist of things that can often get overlooked
- Version numbers: check that the version number is correct in the following files
- README
- INSTALL
- FAQ
- Bio/Root/Version.pm
- Makefile.PL and Build.PL (For Bioperl-run, Bioperl-db etc)
- Change log: make sure it is up-to-date. You may find maintenance/cvs2cl_by_file.pl (based on cvs2cl.pl) helpful in the process:
cvs2cl_by_file.pl --delta bioperl-release-1-5-x:bioperl-release-1-5-y
where 'x' is the previous release and 'y' is the new release.
It is not necessary to make a tag in CVS 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 irrelavent.
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 stable release and gets the name bioperl-1.6.0_001-RC.tar.gz; 1.006000100 gets bioperl-1.6.0.tar.gz; 1.006000101 gets bioperl-1.6.0.1.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.
Tagging the code
We want to tag the code so that it is always possible to go back to the version that was released and fix bugs relative to that release.
$ cd bioperl/core $ cvs tag bioperl-1-X-release
If you are releasing development code that is off the main trunk you can also tag the code as it exists in CVS with the rtag command.
$ cvs -d:ext:YOURNAME@dev.open-bio.org:/home/repository/bioperl rtag bioperl-1-X-release bioperl-live
If this is a new branch of the code (like 1.6.X series) then you need to create a branch. So create a tag that indicates the point where the branch should start from.
$ cvs -d:ext:YOURNAME@dev.open-bio.org:/home/repository/bioperl rtag -r bioperl-1-X bioperl-live $ cvs -d:ext:YOURNAME@dev.open-bio.org:/home/repository/bioperl rtag -b bioperl-1-X_branch bioperl-live
Checkout the code based on the tag
You need to do a fresh cvs export so that you are insuring the posted version is the same as what is in CVS.
$ cvs -d:ext:YOURNAME@dev.open-bio.org:/home/repository/bioperl export -r bioperl-1-X-release -d bioperl-1.X
The -r bioperl-1-X-release tells CVS we want to check out this particular branch. The -d bioperl-1.X tells CVS to check out into this directory.
If changes are going to be made on the branch it is necessary to checkout on the branch
$ cvs -d:ext:YOURNAME@dev.open-bio.org:/home/repository/bioperl co -r bioperl-1-X_branch -d bioperl-1.X_branch
Archives, uploading
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 CVS for information. Make a branch based on the release tag AFTER you are sure the release is okay (you can do this at any point because it is based on the tag which won't move even if more code is checked in to the main trunk).
Update the SRC FTP dir
We provide a plain checkout code for browsing in addition to the CVSWeb and regular CVS 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.
