CONTRIBUTING.md

Contributing

⚠️ TLDR

Create a conda environment with:

```shell
conda env create -f workflows/envs/devel.yml
conda activate devel
pre-commit install --install-hooks
```

then commit with cz commit, and everything should take care of itself!

⚠️ Linux-Dependent

Due to dependencies on Singularity and Nvidia, these steps are Linux-dependent. A workflows/envs/devel_macos.yaml is provided, but it will not support Nvidia/Cuda/GPU acceleration.

Welcome, friend! Open-source software isn't open open-source without the community. We appreciate your interest and welcome all contributions. While your here, we respectfully ask that you abide by our code of conduct. To help keep everything moving smoothly, we have a few guidelines.

Bugs

If you think you've found a bug, let us know here. We'll do our best to deal with it ASAP, but please be patient as we also work many other projects!

Developing

If you think you can fix one of the bugs, or would like to submit a new feature, then let's get coding!

Once you've cloned the repository, fork it, and get your development environment set up. We use conda, nox, and pre-commit to handle environments, testing, and linting. Tests are handled by snakemake. Between them, they make sure that all checks run in isolated environments. Please make sure you activate them before making any changes, using the commands below:

conda env create -f workflows/envs/devel.yml
conda activate devel
pre-commit install --install-hooks

Now, you don't even have to think about linting or testing. When you commit a change, pre-commit will automatically run black, isort, mypy, a suite of flake8-based linters, snakefmt, and snakemake --lint. When you push a change, github actions will trigger a more robust suit using Nox, including security check and snakemake testing.

Sometimes, its useful to run these lints manually. The easiest way to do this is to use pre-commit:

pre-commit run -a

Which will run all lints except the slower security and test checks. To run these, use:

nox -s security

for the former and:

pytest .tests/unit # for unit tests
pytest .tests/integration # for integration tests

for the latter.

Commits

We use a GitHub action for python-semantic-release to manage our version numbers. This automatically parses your commit messages to determine if a new release is nesessary, and, if so, what kind (ie. major, minor, patch). So your commit message is very important!

But we also don't want you stressing about how to format your commit message. To that end, we use a python implementation of commitizen to handle that for you! Just commit using cz commit instead of git commit, and enjoy the magic!

Documentation and Testing

Speaking of documentation and testing - if you add new code, please add documentation and tests for it as well. We use napoleon numpy for our docstrings.

Testing a workflow is a bit different than testing a software package, though the same principles apply. To generate unit tests after changing the analysis scripts, first run the workflow on a small test dataset. Then run:

snakemake --generate-unit-tests

Be careful, as this will reset all existing unit tests. These can be recovered with git reset, so don't worry. Then, using the existing tests as a guide, tweak your new tests until they run.

For integration testing, include all the shell code, data, configuration files, etc., necessary for a minimal run under .tests/integration.

For further details, see Snakemake's own guides here and here.

Review

Once your happy with your code, open a pull-request, and we will reveiw ASAP. If you pull-request is not passing on github actions, or something else confuses us (we are, after all, only human!), we might ask for some small changes. Once everything is looking good, we will merges in your changes!

From the Command-Line

🎆 Optional fun! None of this section is required, but we find it useful and hope you do, too!

If you haven't heard of it already, give a peek to to gh, GitHub's official CLI. It allows to manage all of the above steps from the command-line, from forking, to raising issues, and checking on the status of your pull request. Not a necessity, but for you terminal warriors out there, it just might help!