Skip to content

Latest commit

 

History

History
91 lines (61 loc) · 4.21 KB

CONTRIBUTING.md

File metadata and controls

91 lines (61 loc) · 4.21 KB
Raw

nf-core/tools: Contributing Guidelines

Hi there! Many thanks for taking an interest in improving nf-core/tools.

If you need help then the best place to ask is the #tools channel on the nf-core Slack. You can get an invite on the nf-core website.

Contribution workflow

If you'd like to write some code for nf-core/tools, the standard workflow is as follows:

  1. Check that there isn't already an issue about your idea to avoid duplicating work.
    • If there isn't one already, please create one so that others know you're working on this
  2. Fork the nf-core/tools repository to your GitHub account
  3. Make the necessary changes / additions within your forked repository
  4. Submit a Pull Request against the dev branch and wait for the code to be reviewed and merged.

If you're not used to this workflow with git, you can start with some basic docs from GitHub.

Installing dev requirements

If you want to work with developing the nf-core/tools code, you'll need a couple of extra Python packages. These are listed in requirements-dev.txt and can be installed as follows:

pip install --upgrade -r requirements-dev.txt

Then install your local fork of nf-core/tools:

pip install -e .

Code formatting with Black

All Python code in nf-core/tools must be passed through the Black Python code formatter. This ensures a harmonised code formatting style throughout the package, from all contributors.

You can run Black on the command line (it's included in requirements-dev.txt) - eg. to run recursively on the whole repository:

black .

Alternatively, Black has integrations for most common editors to automatically format code when you hit save. You can also set it up to run when you make a commit.

There is an automated CI check that runs when you open a pull-request to nf-core/tools that will fail if any code does not adhere to Black formatting.

API Documentation

We aim to write function docstrings according to the Google Python style-guide. These are used to automatically generate package documentation on the nf-core website using Sphinx. You can find this documentation here: https://nf-co.re/tools-docs/

If you would like to test the documentation, you can install Sphinx locally by following Sphinx's installation instruction. Once done, you can run make clean and then make html in the root directory of nf-core tools. The HTML will then be generated in docs/api/_build/html.

Tests

When you create a pull request with changes, GitHub Actions will run automatic tests. Typically, pull-requests are only fully reviewed when these tests are passing, though of course we can help out before then.

There are two types of tests that run:

Unit Tests

The nf-core tools package has a set of unit tests bundled, which can be found in the tests/ directory. New features should also come with new tests, to keep the test-coverage high (we use codecov.io to check this automatically).

You can try running the tests locally before pushing code using the following command:

pytest --color=yes tests/

Lint Tests

nf-core/tools contains both the main nf-core template for pipelines and the code used to test that pipelines adhere to the nf-core guidelines. As these two commonly need to be edited together, we test the creation of a pipeline and then linting using a CI check. This ensures that any changes we make to either the linting or the template stay in sync. You can replicate this process locally with the following commands:

nf-core create -n testpipeline -d "This pipeline is for testing"
nf-core lint nf-core-testpipeline