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.11 or higher (for PyPy compatibility).

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.

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 for the presence of relevant compiled wheels, especially for NumPy with PyPy. 

    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 or 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 using PyPy 3.10, which also serves as the PyPy compatibility test.
  • All tests run automatically in CI before the release is published.