Skip to content

Latest commit

 

History

History
114 lines (81 loc) · 5.13 KB

CONTRIBUTING.md

File metadata and controls

114 lines (81 loc) · 5.13 KB
Raw

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 Poetry. Please skim the documentation if you are not familiar with Poetry.

After installing the dependencies with poetry install, you can activate the virtual environment with poetry shell.

Development setup with Conda

You can set up this project with Poetry inside a Conda environment. Running inside a Conda environment can be useful to install difficult to install native dependencies (like numpy). You can install any dependencies that are stubborn before running poetry install.

Install Conda (we use miniforge but any other Conda distribution should work as well).

To create a virtual environment named draco, you can run

conda create -n draco python=3.11
conda activate draco
poetry install

Next time you want to work on Draco, you can just run conda activate draco.

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 poetry show -o to show the latest versions of the packages Draco depends on. Then update the dependencies accordingly.

Run poetry update 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, run poetry version patch/minor/major to update the version number in pyproject.toml.
  • Run git commit -am "chore: bump version to $(poetry version -s)" to commit the version bump and add a tag with git tag "v$(poetry version -s)".
  • Run poetry build to build the package.
  • Configure the PyPI credentials with poetry config pypi-token.pypi <token>.
  • Run poetry publish -r testpypi to publish the package to TestPyPI.
  • Run poetry 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.