Thanks for your interest in Taskgraph! To participate in this community, please review our code of conduct.
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
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:
- Creates a virtualenv for the project in a
.venv
directory (if necessary). - Syncs the project's dependencies as pinned in
uv.lock
(if necessary). - Installs
taskgraph
as an editable package (if necessary). - 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
Tests are run with the pytest framework:
uv run pytest
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.
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.
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>
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>
In order to release a new version of Taskgraph, you will need to:
- Update
CHANGELOG.md
- Update
__version__
insrc/taskgraph/__init__.py
- Commit, and land the above changes with a commit message like "chore: bump <version>"
- Create a release in Github pointing to the above commit. Be sure to also create a new tag matching this version.
- Wait for the
pypi-publish
Github workflow andpush-image-decision
task to finish. - Verify that expected version has been published to pypi and pushed to DockerHub.
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.