If you haven't contributed to open-source before, we recommend you read this excellent guide by GitHub on how to contribute to open source. The guide is long, so you can gloss over things you're familiar with.
If you're not already familiar with it, we follow the fork and pull model on GitHub. Also, check out this recommended git workflow.
This project has a number of requirements for all code contributed.
- We follow the PEP-8 style convention.
- We use Numpy-style docstrings.
- It's ideal if user-facing API changes or new features have documentation added.
After forking and cloning the repository, install in "editable" (i.e. development) mode using the -e option:
git clone https://github.com/open2c/cooler.git
cd cooler
pip install -e .[all]Editable mode installs the package by creating a "link" to the working (repo) directory.
It is best if all new functionality and/or bug fixes have unit tests added with each use-case.
We use pytest as our unit testing framework. Once you've configured your environment, you can just cd to the root of your repository and run
pytestUnit tests are automatically run on Travis CI for pull requests.
If a feature is stable and relatively finalized, it is time to add it to the documentation. If you are adding any private/public functions, it is best to add docstrings, to aid in reviewing code and also for the API reference.
We use Numpy style docstrings and Sphinx to document this library. Sphinx, in turn, uses reStructuredText as its markup language for adding code.
We use the Sphinx Autosummary extension to generate API references. You may want to look at docs/api.rst to see how these files look and where to add new functions, classes or modules.
To build the documentation:
make docsAfter this, you can find an HTML version of the documentation in docs/_build/html/index.html.
Documentation from master and tagged releases is automatically built and hosted thanks to readthedocs.
This document is based off of the guidelines from the sparse project.