Torsten Seemann
Victorian Bioinformatics Consortium, Monash University, Australia.
This document is copyright Torsten Seemann, 2005. It can be copied and distributed under the terms of the Perl Artistic License.
This HOWTO describes the steps you should take to get your patch (enhancement or bug fix) accepted into BioPerl, from checking out the latest version to creating a diff file and submitting it to Bugzilla.
You should ensure you are using the latest developer version of BioPerl - this means checking out bioperl-live from GitHub. Here are instructions on how to do this. This is important because the change you want to make may have already been made!
Let’s imagine you want to modify something in Bio::SeqIO::fasta. First make a backup copy:
cd ~/src/bioperl/bioperl-live
cp Bio/SeqIO/fasta.pm Bio/SeqIO/fasta.pm.orig
Now go ahead and modify Bio/SeqIO/fasta.pm to make the changes you think will enhance the module or rectify a bug. Make sure you check it for syntax too.
perl -I. -c Bio/SeqIO/fasta.pm
You need to now check that you fixed the problem. At this point you will probably re-run the original script which brought the bug to your attention in the first place.
perl -I. /path/to/my_test_script.pl
Although trivial bug fixes will be accepted as-is, anything which modifies functionality or any major change will require a test case for it to be accepted with any confidence. This will mean either adding extra tests to an existing test file (t/fasta.t in this example - make sure you back it up to t/fasta.t.orig), or you will need to create a new test file. I would recommend naming it SeqIO-fasta.t in this case to avoid future clashes. If your test needs data files, place them in t/data/.
cp t/fasta.t t/fasta.t.orig
You need to make sure the test is successful too.
perl -w -I. t/fasta.t
The -w option ensures that all the warnings are reported just like they will be when the perl test harness runs all BioPerl tests.
You now need to produce a difference file for each modified (or new) file related to the patch. There are two ways you can accomplish this:
git diff from the base bioperl-live directory. This is the preferred method for multiple file changes (i.e. test files and modules).By default git diff will show you any uncommitted changes since the last commit.
For single files or directories:
git diff Bio/SeqIO/ > patch.txt
git diff Bio/SeqIO/fasta.pm > patch.txt
For everything:
git diff > patch.txt
diff -Bub Bio/SeqIO/fasta.pm.orig Bio/SeqIO/fasta.pm > fasta-patch.txt
diff -Bub t/fasta.t.orig t/fasta.t > test-patch.txt
Log into the Issues page of bioperl-live on Github. Submit a new feature request, and attach fasta-patch.txt and test-patch.txt to your bug submission. Make sure you write a clear and concise description for the feature request.
Eventually your bug submission will be processed and assimilated into bioperl-live (assuming it wasn’t rejected). A notification will be sent to you, and to the [bioperl-guts-l mailing list, which most BioPerl developers read.
while true; do echo "Waiting..."; sleep 3600; done
Don’t forget to regularly update your Git version of BioPerl!
git pull origin master
It takes a little bit of effort to submit a patch to BioPerl but you are rewarded with that warm fuzzy feeling that giving back to your community provides.