Skip to content

Latest commit

 

History

History
180 lines (113 loc) · 4.66 KB

CONTRIBUTING.rst

File metadata and controls

180 lines (113 loc) · 4.66 KB
Raw

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

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

  1. Update CHANGELOG.md
  2. Update __version__ in src/taskgraph/__init__.py
  3. Commit, and land the above changes with a commit message like "chore: bump <version>"
  4. Create a release in Github pointing to the above commit. Be sure to also create a new tag matching this version.
  5. Wait for the pypi-publish Github workflow and push-image-decision task to finish.
  6. Verify that expected version has been published to pypi and pushed to DockerHub.

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.