Developers

Git convention

The branching model that has been adopted for core BuddySuite developers includes the 'master' branch, a primary 'develop' branch, and 'user-dev' branches. The code in the master branch is essentially the code from the most recent official release, which will have a discrete version number and be included in PyPI. The 'develop' branch is where new code lives, and the user-dev branches are where new code is written. Once a new feature is written and all tests are passing, the user-dev branch can be merged into develop. For non-core contributors pull requests should be made from your fork to the develop branch.

The anatomy of a BuddySuite tool

BuddySuite is structured so that its tools can be used from the command line or imported into other python programs. If you wish to contribute to the project (and we'd love the help!), new features require five distinct 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 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 along with examples

While we would prefer that each developer covers 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

• Header information
• Imports
  • Standard library packages
  • Third party packages
  • BuddySuite specific packages
• Wish list
• Globals
• Core buddy class
• Helper functions
• Main API functions
• Command line UI
  • Internal functions
  • Command line logic

Unit tests

py.test has been chosen as the testing suite, and an output hashing paradigm has been implemented 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 (although, we may move to a SQLite solution in the future). The unfortunate trade-off 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

There are a number of extra third-party programs you will need installed if you wish to run the entire test suite. These include things like RAxML for estimating phylogenetic trees and MAFFT for creating multiple sequence alignments. The list of these dependencies can be found in the installation guide. There is also a script in the main repository called install_dependencies.sh that will attempt to get your environment up to spec (Mac and Linux only).

Release checklist

1. Version should have been incremented in all four Buddy modules and setup.py following previous release, but check
2. Update release date in four Buddy modules
3. Update contributor list in buddy_resources
4. Commit and merge with master branch
5. Run all unit tests locally
6. Confirm PyPI README.rst renders correctly with $: restview README.rst --pypi-strict
7. Push to GitHub
8. Wait until TravisCI completes without errors
9. Run ./setup.py sdist; twine upload dist/*
10. Create a new release on GitHub
11. Increment version in all four Buddy modules and setup.py in develop or maintenance branch and push