Skip to content

Contributing

Bug reports and feature requests

No funding or guaranteed support

TACT is an unfunded project maintained in my spare time. Support is provided on a best-effort basis, and responses may sometimes be delayed.

Open a bug report or a feature request via GitHub Issues.

Developing

Development uses poetry. Simply clone the repository and install:

$ git clone https://github.com/jonchang/tact.git
$ cd tact
$ poetry install

Important: Always use poetry run when executing Python code or commands in this repository to ensure the correct virtual environment and dependencies are used:

$ poetry run python script.py
$ poetry run pytest
$ poetry run tact_add_taxa --version

TACT requires Python 3.12 or higher.

Pull requests

If you spot a bug, opening a pull request to fix it would be appreciated!

On the web version of this documentation, click the edit button (looks like a pencil) to open the text editor to propose changes.

Documentation figures

The SVG figures in docs/img are generated by docs/figures/make_figures.py and committed to the git repository. To change them, edit that script then regenerate them:

$ poetry run python docs/figures/make_figures.py

Colors for the figures are defined in docs/figures/svgfig.py as they need to follow light / dark mode browser settings.

Testing

Tests use pytest. Mostly these are integration tests but there are some unit tests as well.

$ poetry run pytest  # optionally with --script-launch-mode=subprocess

Tests are automatically run on all supported Python versions via GitHub Actions CI.

Releasing

Pre-Release Tasks

  1. Verify CI passes: GitHub Actions

  2. Update outdated packages if needed. Always check that NumPy and SciPy have compiled wheels for every supported Python version, since the Docker image only installs dependencies from wheels. 

    poetry show --outdated
poetry update [package]

  3. Update version in pyproject.toml. For details on versioning, see Semantic Versioning. 

    poetry version patch # (or minor, major)

  4. Review all commits since the last version to ensure nothing is missing. 

    git log --oneline $(git describe --tags --abbrev=0)..HEAD

  5. Update NEWS.md:

    • Document all user-facing changes, relevant dependency updates, and breaking changes.
    • Note: docs/news.md is a symlink to NEWS.md, so updating NEWS.md automatically updates the docs.

  6. Ensure working directory is clean: 

    git status

  7. Commit version and NEWS.md updates: 

    git add pyproject.toml NEWS.md
git commit -m "tact $(poetry version -s)"

Releasing

  1. Create and push tag: 
    VERSION=$(poetry version -s)
git tag v$VERSION
git push --atomic origin master v$VERSION

Note: The tag format must be v*.*.* (e.g., v0.7.0) for GitHub Actions to automatically trigger the release workflows.

Post-Release Verification

After pushing the tag:

  1. GitHub Actions CI/CD: Check workflows succeed

  2. PyPI release: Check package appears and version numbers are correct

  3. Docker Hub release: Check image appears and tags are correct (e.g., 0.7.0, 0.7, 0, latest)

  4. GitHub Packages release: Check image appears and tags are correct (e.g., 0.7.0, 0.7, 0, latest)

  5. Update GitHub release notes: Create a release and include highlights from NEWS.md

  6. Announce new version: Announce on Twitter, Bluesky and other relevant channels

Important notes:

  • GitHub Actions workflows automatically build and publish the new version to PyPI, and build container images for Docker Hub and GitHub Packages when a tag matching v*.*.* is pushed.
  • PyPI publishing uses trusted publishing aka OIDC (no manual upload needed).
  • Docker images are built on the official Python "slim" image, with dependencies pinned to the versions in poetry.lock. Bump PYTHON_VERSION in the Dockerfile when a new Python release has wheels for all dependencies.
  • All tests run automatically in CI before the release is published.