Installation

  1. Clone the pybwa repo (note the --recurse-submodules flag, as bwa is a submodule)

git clone --recurse-submodules https://github.com/fulcrumgenomics/pybwa

  1. Install the environment manager mamba

  2. Install the Python build tool poetry

  3. Create an environment with Python, Cython, and Pysam:

mamba env create -f pybwa.yml

  1. Activate the environment:

mamba activate pybwa

  1. Configure poetry to install into pre-existing virtual environments:

poetry config virtualenvs.create false

  1. Install pybwa into the virtual environment:

poetry install

  1. Check your build:

poetry run pytest

Primary Development Commands

To check and resolve linting issues in the codebase, run:

poetry run ruff check --fix

To check and resolve formatting issues in the codebase, run:

poetry run ruff format

To check the unit tests in the codebase, run:

poetry run pytest

To check the typing in the codebase, run:

poetry run mypy

To generate a code coverage report after testing locally, run:

poetry run coverage html

To check the lock file is up to date:

poetry check --lock

To build the documentation:

cd docs
poetry run make html

Shortcut Task Commands

To be able to run shortcut task commands, first install the Poetry plugin poethepoet:

poetry self add 'poethepoet[poetry_plugin]'

For Running Individual Checks

poetry task check-lock
poetry task check-format
poetry task check-lint
poetry task check-tests
poetry task check-typing
poetry task build-docs

For Running All Checks

poetry task check-all

For Running Individual Fixes

poetry task fix-format
poetry task fix-lint

For Running All Fixes

poetry task fix-all

For Running All Fixes and Checks

poetry task fix-and-check-all

Creating a Release on PyPi

  1. Clone the repository recursively and ensure you are on the main (un-dirty) branch

  2. Checkout a new branch to prepare the library for release

  3. Bump the version of the library to the desired SemVer with poetry version #.#.#

  4. Commit the version bump changes with a Git commit message like chore(release): bump to #.#.#

  5. Push the commit to the upstream remote, open a PR, ensure tests pass, and seek reviews

  6. Squash merge the PR

  7. Tag the new commit on the main branch of the origin repository with the new SemVer

Note

This project follows Semantic Versioning. In brief:

  • MAJOR version when you make incompatible API changes

  • MINOR version when you add functionality in a backwards compatible manner

  • PATCH version when you make backwards compatible bug fixes

GitHub Actions will take care of the remainder of the deployment and release process with:

  1. Unit tests will be run for safety-sake

  2. A source distribution will be built

  3. Multi-arch multi-Python binary distributions will be built

  4. Assets will be deployed to PyPi with the new SemVer

  5. A Conventional Commit-aware changelog will be drafted

  6. A GitHub release will be created with the new SemVer and the drafted changelog

Warning

Consider editing the changelog if there are any errors or necessary enhancements.