Making a BioPerl release
From BioPerl
Contents |
Release schedule
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.
Release style
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.
Creating a release branch
STUB
Checking out branch code
STUB
Note about bug fixes and versioning
STUB
Merging fixes over from the main trunk
STUB
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
You will need to check out the code from Subversion to make the release. 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.
$ svn co svn+ssh://USERNAME@dev.open-bio.org/home/svn-repositories/bioperl/bioperl-live/branches/branch-xy branch-xy
Here is a checklist of things that can often be 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. we formerly used maintenance/cvs2cl_by_file.pl (based on cvs2cl.pl) helpful in the process; we'll be switching to svn2cl
CODE FOR SVN2CL TO BE ADDED
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-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 Subversion 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)
In Subversion, there is really no difference between a tag and a branch beyond the repository directory each appears in (tags in /tags, branches in /branches).
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 SVN::Web and regular Subversion 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.
