Development Setup Guide
A guide for contributing developers.
Clone the project repository
Ensure you have the right permissions, and clone the project repository:
# You need to set up personal-access-tokens
git clone https://gitlab.jatic.net/jatic/reference-implementation/reference-implementation.git
# or
# You need to set up SSH keys
git clone git@gitlab.jatic.net:jatic/reference-implementation/reference-implementation.git
macOS: SSL certificates for non-Homebrew/non-conda Python
If you installed Python from python.org (the framework installer), SSL connections will fail until you run the bundled certificate command:
/Applications/Python\ 3.XX/Install\ Certificates.command
3.XX with your Python version (e.g. 3.12). This is not needed if you installed Python via Homebrew or conda.
Creating an environment
We provide both poetry-based environment and conda-based environment options:
Option 1: Setup poetry environment
To set up a poetry environment, install poetry (the minimum supported version is 2.0.0).
For regular users
You can build the environment by running:
poetry install
For package developers
If you plan to contribute to the project or need development tools, install with development dependencies:
poetry install --with dev
dev and docs are Poetry groups (not pip extras), so pip install .[dev] is not a supported path.
To contribute to the documentation, install with the docs dependencies:
poetry install --with docs
There are also optional dependency groups, ui, reporting, and unsupported:
poetry install --extras ui
poetry install --extras reporting # PDF report export (markdown + xhtml2pdf)
poetry install --extras unsupported
The unsupported extra installs the separate checkmaite-plugins package
with its own unsupported dependencies.
If you want to install all the extras, you can use:
poetry install --all-extras
And if you want to install everything and the kitchen sink:
poetry install --with dev --all-extras
This project utilizes pre-commit for linting and formatting. Developers should also install the pre-commit hooks using:
poetry run pre-commit install
NOTE If you have a poetry environment installed, you can also use this bash command from the root of your cloned checkmaite directory to install dev dependencies and pre-commit hooks in one step:
make init
Option 2: Setup conda environment
To set up a conda environment, install conda on your machine and build the environment by running:
# create env with conda-lock installed
conda create -n checkmaite "conda-lock>=3"
# activate the environment
conda activate checkmaite
# use conda-lock to install dependencies
CONDA_ENV_NAME=checkmaite make conda-env
# finally, install the `checkmaite` package
pip install -e . --no-deps
This project utilizes pre-commit for linting and formatting. Install the pre-commit hooks using:
pre-commit install
Testing
(In the following, instructions are only provided for poetry. Similar instructions are valid for conda.)
This project uses pytest for it's test suite. Run the full test suite with:
poetry run pytest tests -svv
This project also contains test markers to flag special test groups. The tests marked real_data are
time consuming tests that utilize real data. The unsupported capability tests are maintained in the
checkmaite-plugins repository.
You can run them manually with:
poetry run pytest tests -svv -m real_data
NOTE If you have a poetry environment installed, you can also use this bash command from the root of your cloned checkmaite directory to run tests with coverage:
make test
Linting and formatting
(In the following, instructions are only provided for poetry. Similar instructions are valid for conda.)
Linting and formatting are automated via pre-commit hooks. However, if you'd like to run them directly, you can run:
poetry run pre-commit run --all-files --verbose
NOTE If you have a poetry environment installed, you can also use this bash command from the root of your cloned checkmaite directory to run all pre-commit hooks:
make format
Type checking is performed by pyright. This can be run using:
poetry run pyright src
Building the docs
(In the following, instructions are only provided for poetry. Similar instructions are valid for conda.)
The documentation is built using mkdocs and deployed via CI to GitLab Pages. checkmaite also makes use of the mkdocs-jupyter plugin which allows the docs to be build from notebooks as well as the standard markdown.
The docs can be built locally in two different ways. To build the docs with a live-reloading server, use:
poetry run mkdocs serve
This will create a live server running on the local machine. Any changes made to the document will be live-reloaded in the local website.
Alternately, the docs can be built locally as a static site similar to the process in CI by running:
poetry run mkdocs build --site-dir public
The site-dir flag is optional and it defaults to building the site under ./public in the directory in which you ran the command.
The checkmaite documentation website is deployed at https://jatic.pages.jatic.net/reference-implementation/reference-implementation.
Setting minimum package versions
The JATIC Software Development Plan (SDP) requires that all dependencies include a minimum version. It is preferable that these minimums be valid minimums due to a real incompatibility with the previous version. However, discovering the true minimums in a complex environment is highly time consuming. For this reason, we ask that miminums be set (in compliance with the SDP), but that they be comment tagged as either "necessary" (you are aware of an incompatibility with the previous version) or "arbitrary" (you set this version artitrarily and it may be lowered if an issue with cross-compatibility arises).
Conda lock file
Using the Lock File Locally
run the following
CONDA_ENV_NAME=<env-name> make conda-env
The CONDA_ENV_NAME environment variable is optional and defaults to checkmaite.
Updating the lockfile
To update the lockfile (e.g. after changing pyproject.yaml), run the following:
make conda-lock
Running the GitLab CI locally
We use gitlab-ci-local to run the GitLab CI on our local machines. It is an open-source CLI that lets us run GitLab CI jobs locally using the same .gitlab-ci.yml that we use in GitLab. This is handy for debugging CI without pushing commits. Please see the gitlab-ci-local repository README for how to install gitlab-ci-local.
gitlab-ci-local can execute jobs via a Docker container or directly on your machine (shell executor). We follow the Docker approach and so you will need to have Docker available locally before you can use the tool.
To run GitLab CI locally, we have created a special file .gitlab-ci-local-variables.yml. You should generate a PAT on GitLab (contact the checkmaite team if you do not know how to do this) and then update the GITLAB_CI_TOKEN: field in .gitlab-ci-local-variables.yml with this value.
To run a single job, it's as simple as running gitlab-ci-local run lint (you can replace lint with any job name from .gitlab-ci.yml such as test or pages-branch). A Docker container should then start and you should be able to replicate the GitLab CI experience locally.
How it works
The way that gitlab-ci-local works is that it parses your .gitlab-ci.yml alongside .gitlab-ci-local-variables.yml, builds the job graph, and then runs the job(s) you ask for. You can list the jobs it would run with --list. If a job specifies image: (this is what we recommend), it spins up that Docker image and runs your before_script/script/after_script inside it.