HOWTO:SubmitPatch
From BioPerl
Contents |
Author
Torsten Seemann <torsten.seemann-at-infotech-monash-edu-au>
Victorian Bioinformatics Consortium, Monash University, Australia.
Copyright
This document is copyright Torsten Seemann, 2005. It can be copied and distributed under the terms of the Perl Artistic License.
Revisions
- First draft - Tseemann 02:50, 29 December 2005 (EST)
Introduction
This HOWTO describes the steps you should take to get your patch (enhancement or bug fix) accepted into BioPerl, from checking out the latest CVS to creating a diff file and submitting it to Bugzilla.
Step by Step
Get the latest CVS version
You should ensure you are using the latest developer version of BioPerl - this means checking out bioperl-live (or the appropriate repository) from CVS. Here are instructions on how to do this. This is important because the change you want to make may have already been made!
mkdir -p ~/src/bioperl cd ~/src/bioperl cvs -d :pserver:cvs@code.open-bio.org:/home/repository/bioperl login (password is "cvs") cvs -d :pserver:cvs@code.open-bio.org:/home/repository/bioperl checkout bioperl-live
Back up the original file
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
Modify the file
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
Try your script
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
Write a test
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
Run the test
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.
Make the patch
You now need to produce a difference file for each modified (or new) file related to the patch. This is done with the diff tool in Unix.
diff -Bub Bio/SeqIO/fasta.pm.orig Bio/SeqIO/fasta.pm > /tmp/fasta.pm.diff diff -Bub t/fasta.t.orig t/fasta.t > /tmp/fasta.t.diff
Submit the patch
First read about Bugs then log into http://bugzilla.bioperl.org/ . Click on Submit new bug and attach /tmp/fasta.pm.diff and /tmp/fasta.t.diff to your bug submission. Make sure you write a clear and concise description for the bug. Minor note to those not familiar with Bugzilla, the 'attach' option appears after you have actually submitted the bug report.
firefox http://bugzilla.bioperl.org/
The waiting game
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
Update your CVS
Don't forget to regularly update your CVS version of BioPerl!
cvs update -dP
Conclusion
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. If the patch showed BioPerl aptitude, there's a good chance that you will be invited to become a BioPerl developer via your own developer account.
Further reading
Categories: HOWTOs | TODO
