Developers - mendessoares/BuddySuite GitHub Wiki

The Git branching model outlined by Vincent Driessen has been adopted for development of BuddySuite. In essence, all new work should be done on the 'develop' branch, and any new functions or significant modifications to core functionality should be worked on in a separate feature branch (to be merged with 'develop' once all unit tests pass). Merges with 'master' will be considered release versions, and will be handled by the core dev team.

The Buddy tools are structured so they can be used as importable modules as well as command line programs. If you wish to contribute to the project (and we'd love the help!), new features require five components:

  1. A self contained function in the 'MAIN API FUNCTIONS' section that accepts a buddy object as input and (usually) returns a new/modified buddy object as output.
  2. An entry in the relevant 'flags' dictionary in the workshop/buddy_resources.py module (e.g., sb_flags for SeqBuddy). This is processed at runtime to populate argparse, which allows the function to be called from the command line.
  3. Wrapper code in the 'COMMAND LINE LOGIC' section to handle command line calls.
  4. Unit tests, written for py.test, that cover both the main API function and the command line logic.
  5. A wiki page describing the command line component and including at least one use case

While we would prefer it if developers cover all five of these requirements for any new feature they create, we're definitely not going to turn people away! Don't be shy about asking for help if you need it.

Please follow the PEP8 style guide as closely as possible.

Structure of BuddySuite modules

With the exception of DatabaseBuddy, all BuddySuite modules are sub-divided into the following sections

##Unit tests While not quite there yet, the goal is to cover over 90% of the BuddySuite code base. We have selected pytest as our testing suite, and have implemented an output hashing paradigm to compare test runs against expected results. Hashes were chosen instead of full string comparisons to keep the amount of test data to manageable levels; the other options were many hundreds of individual files or many thousands of lines within the actual test scripts. The unfortunate tradeoff with our hashing system is a less informative error message when tests fail, but there are workarounds. See the Unit Test page for details.

##Dependencies If you are cloning the repository directly, you will not be getting all of the necessary dependencies to run the BuddySuite. Without exception, you must have access to BioPython in your python PATH. Note that versions of BioPython earlier than 16.6 have issues when dealing with SeqRecord features that will cause some unit tests to fail, so please ensure you are using the most up-to-date package. All other dependencies are module specific (listed below), so feel free to pick and choose depending on which module you are developing.

####SeqBuddy Certain BLAST binaries (blastcmd, blastp, and blastn) from the NCBI C++ tool kit are required for several tools in SeqBuddy. These binaries are included in the BuddySuite repo, so just copy them from /workshop/build_dir/blast_binaries to somewhere in your PATH.

####AlignBuddy AlignBuddy wraps the following third party alignment programs:

To run the full alignbuddy_test.py script, current versions all of these programs must be operational on your system. Alternatively, exclude the alignment tests:

$: py.test alignbuddy_test.py -m "not generate_alignments"

####PhyloBuddy PhyloBuddy depends on the third party python packages DendroPy and ETE3 (which depends on PyQt and six, ugh...), and also wraps the following phylogenetic inference packages.

Similar to AlignBuddy, the phylogenetics software is optional. Exclude them from the unit tests as follows:

$: py.test phylobuddy_test.py -m "not generate_trees"