Skip to content

Latest commit

 

History

History
93 lines (66 loc) · 4.59 KB

CONTRIBUTING.md

File metadata and controls

93 lines (66 loc) · 4.59 KB

Contributing to Draco

We welcome any input, feedback, bug reports, and contributions via Draco's GitHub Repository.

This document describes how you can set up your development environment if you want to contribute to the code.

Development setup

This project uses uv. Please skim the documentation if you are not familiar with uv.

After installing the dependencies with uv sync, you can run commands in the virtual environment with uv run <command> or activate it manually with source .venv/bin/activate (or .venv\Scripts\activate on Windows).

Install the pre-commit hooks

Install pre-commit and then install the hooks with pre-commit install. These hooks will automatically format code before making a new commit.

Make commands

You can run various test and lint commands via make. For example, run make test to run the tests. Or just make to run tests, lint, and type checks.

Update dependencies

Run uv tree --outdated -d1 to show the latest versions of the packages Draco depends on. Then update the dependencies accordingly.

Run uv lock --upgrade to update dependencies within the specified range and update the lockfile.

Writing constraints

For more information about writing constraints and optimization-based problems, take a look at the Pottasco guide.

Server Development

You can start the custom FastAPI server in hot-reload mode with make serve. This way, you can make changes to the server code and see the changes immediately. You can explore the API by visiting the OpenAPI docs at http://localhost:8000/docs.

Development with Docker

We provide a pre-configured Docker environment for a better developer experience. You can execute the following commands from a UNIX shell to start the development environment:

# Build the docker image
NB_USER="draco2" && \
docker build --build-arg NB_USER=${NB_USER} -t draco2-dev . && \
# Start a container with local volume mounting and port forwarding for
# [Jupyter Book, FastAPI, Jupyter, Pyodide Console, JupyterLite]
docker run -it --rm \
               -v $(pwd):/home/${NB_USER}/app \
               -p 5000:5000 \
               -p 8000:8000 \
               -p 8888:8888 \
               -p 9000:9000 \
               -p 9999:9999 \
               --name draco2-dev draco2-dev bash

As soon as you are inside the container's shell, you can execute make targets as you would from your local machine. You can run make test to verify that everything is working as expected.

The services for which we reserved the ports are:

You can open new shells inside the running container with docker exec -it draco2-dev bash. This way it is OK to run the above-listed commands which 'block' your current shell session.

Making a release

  • After pulling the latest commits, manually update the version number in pyproject.toml.
  • Run git commit -am "chore: bump version to <new-version>" to commit the version bump and add a tag with git tag "v<new-version>".
  • Run uv build to build the package.
  • Configure PyPI credentials (e.g., in ~/.pypirc or use environment variables for authentication).
  • Run uv publish --index-url https://test.pypi.org/legacy/ to publish the package to TestPyPI.
  • Run uv publish to publish the package to PyPI.
  • Push the commits and tags with git push && git push --tags.
  • Create a release on GitHub for the new version tag.

Pyodide Distributions Release

The Pyodide distribution used for Jupyter Lite and the Pyodide Console will be automatically attached to the GitHub release via .github/workflows/build.yml#pin_distro. To make the integration of Draco into web applications easier we also publish the Pyodide distribution to NPM via .github/workflows/build.yml#npm_publish. The NPM package is called draco-pyodide and can be installed as any other NPM package.