|
| 1 | +# Truvari API |
| 2 | +Many of the helper methods/objects are documented such that developers can reuse truvari in their own code. To see developer documentation, visit [readthedocs](https://truvari.readthedocs.io/en/latest/). |
| 3 | + |
| 4 | +Documentation can also be seen using |
| 5 | +```python |
| 6 | +import truvari |
| 7 | +help(truvari) |
| 8 | +``` |
| 9 | + |
| 10 | +# docker |
| 11 | + |
| 12 | +A Dockerfile exists to build an image of Truvari. To make a Docker image, clone the repository and run |
| 13 | +```bash |
| 14 | +docker build -t truvari . |
| 15 | +``` |
| 16 | + |
| 17 | +You can then run Truvari through docker using |
| 18 | +```bash |
| 19 | +docker run -v `pwd`:/data -it truvari |
| 20 | +``` |
| 21 | +Where `pwd` can be whatever directory you'd like to mount in the docker to the path `/data/`, which is the working directory for the Truvari run. You can provide parameters directly to the entry point. |
| 22 | +```bash |
| 23 | +docker run -v `pwd`:/data -it truvari anno svinfo -i example.vcf.gz |
| 24 | +``` |
| 25 | + |
| 26 | +If you'd like to interact within the docker container for things like running the CI/CD scripts |
| 27 | +```bash |
| 28 | +docker run -v `pwd`:/data --entrypoint /bin/bash -it truvari |
| 29 | +``` |
| 30 | +You'll now be inside the container and can run FuncTests or run Truvari directly |
| 31 | +```bash |
| 32 | +bash repo_utils/truvari_ssshtests.sh |
| 33 | +truvari anno svinfo -i example.vcf.gz |
| 34 | +``` |
| 35 | + |
| 36 | +# CI/CD |
| 37 | + |
| 38 | +Scripts that help ensure the tool's quality. Extra dependencies need to be installed in order to run Truvari's CI/CD scripts. |
| 39 | + |
| 40 | +```bash |
| 41 | +pip install pylint anybadge coverage |
| 42 | +``` |
| 43 | + |
| 44 | +Check code formatting with |
| 45 | +```bash |
| 46 | +python repo_utils/pylint_maker.py |
| 47 | +``` |
| 48 | +We use [autopep8](https://pypi.org/project/autopep8/) (via [vim-autopep8](https://github.com/tell-k/vim-autopep8)) for formatting. |
| 49 | + |
| 50 | +Test the code and generate a coverage report with |
| 51 | +```bash |
| 52 | +bash repo_utils/truvari_ssshtests.sh |
| 53 | +``` |
| 54 | + |
| 55 | +Truvari leverages github actions to perform these checks when new code is pushed to the repository. We've noticed that the actions sometimes hangs through no fault of the code. If this happens, cancel and resubmit the job. Once FuncTests are successful, it uploads an artifact of the `coverage html` report which you can download to see a line-by-line accounting of test coverage. |
| 56 | + |
| 57 | +# git flow |
| 58 | + |
| 59 | +To organize the commits for the repository, we use [git-flow](https://danielkummer.github.io/git-flow-cheatsheet/). Therefore, `develop` is the default branch, the latest tagged release is on `master`, and new, in-development features are within `feature/<name>` |
| 60 | + |
| 61 | +When contributing to the code, be sure you're working off of develop and have run `git flow init`. |
| 62 | + |
| 63 | +# versioning |
| 64 | + |
| 65 | +Truvari uses [Semantic Versioning](https://semver.org/). As of v3.0.0, a single version is kept in the code under `truvari/__init__.__version__`. We try to keep the suffix `-dev` on the version in the develop branch. When cutting a new release, we may replace the suffix with `-rc` if we've built a release candidate that may need more testing/development. Once we've committed to a full release that will be pushed to PyPi, no suffix is placed on the version. |
| 66 | + |
| 67 | +# docs |
| 68 | + |
| 69 | +The github wiki serves the documentation most relevant to the `develop/` branch. When cutting a new release, we freeze and version the wiki's documentation with the helper utility `docs/freeze_wiki.sh`. |
| 70 | + |
| 71 | +# Creating a release |
| 72 | +Follow these steps to create a release |
| 73 | + |
| 74 | +0) Bump release version |
| 75 | +1) Run tests locally |
| 76 | +2) Update API Docs |
| 77 | +3) Freeze the Wiki |
| 78 | +4) Ensure all code is checked in |
| 79 | +5) Do a [git-flow release](https://danielkummer.github.io/git-flow-cheatsheet/) |
| 80 | +6) Use github action to make a testpypi release |
| 81 | +7) Check test release |
| 82 | +```bash |
| 83 | +python3 -m venv test_truvari |
| 84 | +python3 -m pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple/ truvari |
| 85 | +``` |
| 86 | +8) Use GitHub action to make a pypi release |
| 87 | +9) Change Updates Wiki |
| 88 | +10) Download release-tarball.zip from step #8’s action |
| 89 | +11) Create release (include #9) from the tag |
| 90 | +12) Checkout develop and Bump to dev version and README ‘commits since’ badge |
0 commit comments