Development Setup

Development Setup#

This page covers everything you need to run the full CI-equivalent checks locally before opening a pull request.

Prerequisites#

  • Docker

  • Python 3.12+

  • GNU Make

  • Git

One-time setup#

# Clone the repository (SSH, recommended)
git clone git@github.com:jupyter/docker-stacks.git
# or via HTTPS
git clone https://github.com/jupyter/docker-stacks.git

cd docker-stacks

# Install Python development dependencies
pip install --upgrade -r requirements-dev.txt

# Install pre-commit hooks (runs linters automatically on git commit)
pre-commit install --install-hooks

Pre-PR checklist#

Run these steps locally before pushing.

# 1. Run all linters including mypy
pre-commit run --all-files --hook-stage manual

# 2. Build the image you changed
make build/<image-name>

# 3. Run tests for that image
make test/<image-name>

Note

If the parent image isn’t built locally, Docker pulls it from the registry. This means changes to a parent image won’t be reflected unless you also rebuild it locally.

Replace <image-name> with the image you modified (e.g., docker-stacks-foundation, base-notebook, scipy-notebook).

Note

make test/<image-name> runs the tests for that image plus every parent image’s tests against it (e.g., testing scipy-notebook also runs base-notebook and docker-stacks-foundation test files against the scipy-notebook image). CI additionally runs the same test set against every downstream image, so a change in docker-stacks-foundation is verified across all images in CI even though locally you’d only run make test/docker-stacks-foundation.

Common examples#

# Working on the foundation image (start scripts, logging, etc.)
pre-commit run --all-files --hook-stage manual
make build/docker-stacks-foundation
make test/docker-stacks-foundation

# Working on the base notebook image
pre-commit run --all-files --hook-stage manual
make build/docker-stacks-foundation
make build/base-notebook
make test/base-notebook

# Build and test every image (slow; mainly useful before opening a PR
# that changes the foundation or base image)
make build-all
make test-all