⚠️ TLDRCreate a conda environment with:
```shell conda env create -f workflows/envs/devel.yml conda activate GTExSnake pre-commit install --install-hooks ```then commit with
cz commit, and everything should take care of itself!
⚠️ Linux-DependentDue to dependencies on Singularity, these steps are Linux specific.
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.
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!
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 GTExSnake
pre-commit install --install-hooksNow,
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 -aWhich will run all lints except the slower security and test checks. To run these, use:
nox -s securityfor the former and:
pytest .tests/unit # for unit tests
pytest .tests/integration # for integration tests
for the latter.
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!
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-testsBe 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.
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!
🎆 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!