So you want to contribute to Biopython, huh? Great! New contributions are the lifeblood of the project. However, if done incorrectly, they can quickly suck up valuable developer time. (We have day jobs too!) This is a short guide to the recommended way to contribute code to Biopython.
See also the chapter about contributing in the Tutorial (PDF).
If you get as far as making a pull request with changes, you should read CONTRIBUTING.rst which describes how the automated testing including style checks are done.
Even if you don’t feel ready or able to contribute code, you can still help out. There always things that can be improved on the documentation (even just proof reading, or telling us if a section isn’t clear enough). We also need people on the mailing lists to help out with beginner’s questions, or to participate in debates about new features. Maybe you can propose general examples for the wiki cookbook?
The best contributions are the code that you have already been using in your daily research. This should be code that you think might be useful for other people and is already free of bugs. If you are thinking of sending this in, go on to Step 2, Submitting Code!
Otherwise, there are still many ways to contribute to Biopython, both involving coding and not. Some things that you can help on include:
In general, we will consider any code that is applicable to biological or chemical data. Please do not submit code whose functionality largely overlaps with code already in Biopython, unless there is an obvious improvement and you have a plan for integrating the code.
Before you submit it, please check that:
If all these terms seem acceptable, please send a description of your code to email@example.com (see Mailing lists). Be sure to subscribe to biopython mailing list before sending a message, otherwise your message will be discarded by the mail server (this was done to avoid spam on the mailing list). Don’t send the code directly to the biopython mailing list. Instead, please use our GitHub page by creating an issue and either attaching the file(s) or linking to your GitHub branch.
Biopython tries to follow the coding conventions laid out in PEP 8 and PEP 257. The important highlights are:
The one notable exception is module names, where we tend to use title case. With hindsight this is unfortunate, but we are constrained by backwards compatibility.
Epydoc and/or Sphinx apidoc is being used to generate automatic documentation of the source code so it definitely is useful to put helpful comments in your code so that they will be reflected in the API documentation (in addition to all the normal reasons to document code).
We generally don’t do anything fancy to try and format the comments in the code – but they are interpreted as reStructuredText markup which allows things like bullet points and italics. This isn’t fancy, but it’s effective and easier then trying to deal with the myriad of different ways to try and structure source code comments.
However, there are a few tricks to make your documentation look its best. The main ones are:
Here’s an example of a module documented so that epydoc will be happy:
"""This is a one line description of the module followed with a period. More information about the module and its goals and usage. """ class MyClass: """One line description of the class followed by a period. More information about the class -- its purpose, usage, and implementation. """ def my_function(self, spam): """A terse description of my function followed with a period. A longer description with all kinds of additional goodies. This may include information about what the function does, along with what parameters it will be passed and what it returns. You know, information so people know how to use the function. """ # the code ...