CONTRIBUTING.md

Contributing to miniwdl

Feedback and contributions to miniwdl are welcome, via issues and pull requests on this repository.

• Online documentation includes several "codelab" tutorials to start with
• The Project board shows our current prioritization of issues
• Starter issues are suitable entry points for new contributors
• Pull request template includes a preparation checklist

Development environment

To set up your Linux development environment,

1. git clone --recursive this repository or your fork thereof, and cd into it
2. Install OS packages as illustrated in the Dockerfile (OS packages) and PyPI dependencies with pip3 install '.[dev]'
3. Invoking user must have permission to control Docker
4. Try python3 -m WDL run_self_test to test the configuration

Generally, python3 -m WDL ... invokes the equivalent of the miniwdl ... entry point for the local source tree. Another option is to pip3 install . to install the miniwdl entry point with the current code revision.

The Makefile has a few typical flows:

• make or make test runs the full test suite with code coverage report (takes several minutes)
• make qtest runs most of the tests more quickly (by omitting some slower cases, and not tracking coverage)
• make pretty reformats the code with ruff format
• make check validates the code with ruff check and mypy

To quickly run only a relevant subset of the tests, you can e.g. python3 -m unittest -f tests/test_5stdlib.py or python3 -m unittest -f tests.test_5stdlib.TestStdLib.test_glob.

macOS: isn't preferred for miniwdl development due to some test suite incompatibilities; but at least simple changes can be prototyped under macOS.

Read the Docs currently builds from the mlin/miniwdl fork of this repository. Locally, make doc generates the docs under docs/_build/html/.

Releases, tags, and branches

Release version numbers follow the semantic versioning convention (vA.B.C; A=Major B=Minor C=Patch). Each release is created from a git tag of the version number, then published through GitHub, PyPI, and conda-forge.

The repository has the following principal branches:

• main is the trunk, with all diffs pending for the upcoming mainline release
• release should be set to the most up-to-date mainline release
• vA.B.x track older release lineages, kept in case of need to release patched versions thereof

Security

Please disclose security issues responsibly by contacting security@chanzuckerberg.com.