Contributing to Taskgraph

Contributing to Taskgraph#

Thanks for your interest in Taskgraph! To participate in this community, please review our code of conduct.

Clone the Repo#

To contribute to Taskgraph or use the debugging tools, you’ll need to clone the repository:

# first fork taskgraph
git clone https://github.com/<user>/taskgraph
cd taskgraph
git remote add upstream https://github.com/taskcluster/taskgraph

Run Taskgraph#

We use a tool called uv to manage Taskgraph and its dependencies. First, follow the installation instructions. Then run:

uv run taskgraph --help

The uv run command does several things:

  1. Creates a virtualenv for the project in a .venv directory (if necessary).

  2. Syncs the project’s dependencies as pinned in uv.lock (if necessary).

  3. Installs taskgraph as an editable package (if necessary).

  4. Invokes the specified command (in this case taskgraph --help).

Anytime you wish to run a command within the project’s virtualenv, prefix it with uv run. Alternatively you can activate the virtualenv as normal:

source .venv/bin/activate
taskgraph --help

Just beware that with this method, the dependencies won’t automatically be synced prior to running your command. You can still sync dependencies manually with:

uv sync

Running Tests#

Tests are run with the pytest framework:

uv run pytest

Running Checks#

Linters and formatters are run via pre-commit. To install the hooks, run:

$ pre-commit install -t pre-commit -t commit-msg

Now checks will automatically run on every commit. If you prefer to run checks manually, you can use:

$ pre-commit run

Some of the checks we enforce include ruff and yamllint. See pre-commit-config.yaml for a full list.

Working with Documentation#

The Taskgraph repo uses Sphinx to generate the documentation. To work on the docs, run:

uv run make livehtml

This will start a live server that automatically re-generates when you edit a documentation file. Alternatively you can generate static docs under the docs/_build directory:

uv run make html

Taskgraph also uses the autodoc extension to generate an API reference. When new modules are created, be sure to add an autodoc directive for them in the source reference.

Managing Dependencies#

Adding a New Dependency#

To add a new dependency to Taskgraph, run:

uv add <dependency>

To add a new dependency that is only used in the development process, run:

uv add --dev <dependency>

Updating Existing Dependencies#

If you’d like to update all dependencies within their constraints defined in the pyproject.toml file, run:

uv sync -U

Or if you’d like to update a specific dependency:

uv sync -P <package>

Releasing taskcluster-taskgraph#

In order to release a new version of Taskgraph, you will need to:

  1. Update CHANGELOG.md

  2. Update version in pyproject.toml

  3. Run uv lock

  4. Commit, and land the above changes with a commit message like “chore: bump <version>”

  5. Draft a release in Github pointing to the above commit.

    1. Create a new tag of the form X.Y.Z

    2. Ensure “Set as latest release” is checked

    3. Submit the release

  6. Wait for the pypi-publish Github workflow and push-image-decision task to finish.

  7. Verify that expected version has been published to pypi and pushed to DockerHub.

Releasing pytest-taskgraph#

There’s also a Pytest plugin packaged under packages/pytest-taskgraph. The release process for this package is:

  1. Update version in packages/pytest-taskgraph/pyproject.toml, and run uv lock

  2. Commit and land the changes with a commit message like “chore: bump pytest-taskgraph <version>”

  3. Draft a release in Github pointing to the above commit.

    1. Create a new tag of the form pytest-taskgraph-vX.Y.Z

    2. Uncheck “Set as latest release”

    3. Submit the release

  4. Wait for the pypi-publish Github workflow to finish.

  5. Verify that expected version has been published to pypi.

Building the Package#

Typically building the package manually is not required, as this is handled in automation prior to release. However, if you’d like to test the package builds manually, you can do so with:

uvx --from build pyproject-build --installer uv

Source and wheel distributions will be available under the dist/ directory.