Development Workflow#
Here are instructions for setting up a development environment for the Gateway Provisioners project. It also includes common steps in the developer workflow such as building Gateway Provisioners, running tests, building docs, etc.
Prerequisites#
There are a couple of globally-scoped commands that are necessary to build Gateway Provisioners: make
and sbt
.
make
#
Our build framework is based on make
so please ensure that GNU make is
installed on your system.
Important!
If you use the typical python -m build --wheel
or hatch run build
commands, the Scala Launcher build (see next item)
will not occur! Always use make dist
to build the distribution.
sbt
#
Our Scala launcher is built using sbt
(Scala Build Tool). Please check
here for installation instructions for your platform.
Clone the repo#
Clone this repository into a local directory.
# make a directory under your HOME directory to put the source code
mkdir -p ~/projects
cd ~/projects
# clone this repo
git clone https://github.com/jupyter-server/gateway_provisioners.git
Make#
Gateway Provisioner’s build environment is centered around make
and the
corresponding Makefile
.
Entering make
with no parameters yields the following:
clean-images Remove all docker images. Targets clean-base-images, clean-kernel-images, and clean-app-images can also be used.
clean Remove all build, test, coverage, and Python artifacts
dist Build wheel and source distributions
docs Generate Sphinx HTML documentation, including API docs
helm-chart Make helm chart distribution
images Build all docker images. Targets base-images, kernel-images, and app-images can also be used.
install Install the built package to the active Python's site-packages
lint-fix Run lint with updates enabled
lint Check style and linting
push-images Push all docker images. Targets push-base-images, push-kernel-images, push-app-images can also be used.
release Package and upload a release using twine
test Run tests with the currently active Python version
A typical sequence of commands might include the following:
Clean the current build environment
make clean
Apply changes and ensure updates pass lint
make lint
If lint-related errors are present, they can usually be fixed using
lint-fix
make lint-fix
Build the distribution
make dist
Run tests via Makefile (
pytest -v
)make test
Build the docs
make docs
Build the images
make images
See also
See Kernel-image Dockerfiles in our Operators Guide for additional information regarding image Dockerfiles, build arguments, etc.