Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
103 lines (63 loc) · 4.48 KB

CONTRIBUTING.md

File metadata and controls

103 lines (63 loc) · 4.48 KB
Raw

Contributing to dstack

We appreciate your interest in contributing to dstack! This document will help you get up to speed with dstack codebase and guide you through the contribution process.

Who can contribute

We'd be happy to see your contribution if you are a dstack user, a partner integrating with dstack, or any other person genuinely interested in dstack.

Using AI assistance

You may use AI assistance when contributing to dstack. However, we expect you, the human contributor, to initiate and validate the contribution, ensuring it meets the same standard as something you'd write by hand.

Contributions made entirely without a human in the loop (e.g., PRs filed by an autonomous agent against open issues) are discouraged and will be declined.

Accepted changes

  • Bug fixes that address a bug you've hit while using dstack. Include steps to reproduce in the linked issue or the PR.
  • New features that improve dstack for you. Before submitting a feature PR, please describe your use case and proposal in a GitHub issue to discuss it with the core team.
  • Minor fixes such as typos.
  • Examples.

Existing open issues are typically picked up by the core team — please only contribute to one if it actually affects how you use dstack.

Set up your development environment

Follow contributing/DEVELOPMENT.md.

Learn dstack internals

If you make a non-trivial change to dstack, we recommend you learn about dstack internals. A good place to start is contributing/ARCHITECTURE.md.

Make a PR

  1. Look for an existing issue or create a new one.
  2. Fork the repo.
  3. Commit your changes.
  4. Open a PR. Link the PR to the issue (if you are solving one).

Before pushing your changes

We use ruff to format Python code and to sort Python imports. Before committing your changes, run:

  1. uv run ruff check --fix
  2. uv run ruff format

There are also helper pre-commits installed for ruff that make commits fail if the code is not formatted or the imports are not sorted. They also change the code as required so that you can review the changes and commit again.

Run tests

It's recommended to run tests locally before running them in CI. To run Python tests, first ensure you've install dev dependencies as described in contributing/DEVELOPMENT.md. Then you can do:

uv run pytest src/tests

(Optionally) By default, tests run against SQLite. Use the --runpostgres flag to run the tests against Postgres as well:

uv run pytest src/tests --runpostgres

Alternatively, you can run tests via tox inside an isolated environment ensuring that the dstack package itself is built correctly and all requirements are specified and correct. tox and just must be already installed.

  • Run tests in the default environment:

    just tox::test-default

    The Python version of the default environment is configured via the .python-version file in the repo root directory. Note, the same file is used by uv.

  • Run tests against all currently supported Python versions:

    just tox::test-supported

  • Run tests in the current environment:

    just tox::test-current

    It saves about 30-60 seconds at the cost of Python environment isolation (defeating the core purpose of tox) — no packages are built or installed, and, as a consequence, all dependencies must be already installed, but, unlike the plain pytest command, the process environment variables are still isolated.

It's possible to pass pytest arguments after the -- separator (the arguments before the separator are tox run arguments):

just tox::test-default -- -vvv --last-failed

Add a new backend

If you'd like to integrate a new cloud provider to dstack, follow contributing/BACKENDS.md.

What's next

You can find more subject-focused guides in the contributing directory.

If you have any questions, you can always get help in our Discord community.