Tutorial: Get started with development

Tutorial: Get started with development

Follow this tutorial to set up a local copy of the code for development of the workflow itself. This is not necessary if you only want to use HERMES or want to develop an extension plugin loaded at runtime.

Prepare your environment

First, install Python 3.10 (or later).

Additionally, you need to install poetry >= 1.2.0, either globally, or within an environment of your choice. As a project, we chose poetry to manage our dependencies, builds, and deposits as a state of the art solution within the Python ecosystem.

Get the source code

Next, you need to obtain a version of the HERMES source code.

You can either download it as a zipped package or clone the whole Git repository. You can clone the repository and enter the project directory as follows:

git clone https://gitlab.com/hermes-hmc/hermes.git
cd hermes

Learn how our repo is structured

  • All Python sources are in the src folder

  • pytest tests are in the test folder

  • Architectural Decision Records (ADR) are in docs/adr

  • API documentation is automatically generated into docs/source/api

  • All other Sphinx-based documentation lives in docs/source/*

This project uses

  • a development branch (develop) to merge developments into, this is the default branch

  • actual development is done on “feature” branches (this includes non-feature work such as bug fixing), see also our Contribution Guidelines.

  • a main branch which only includes releases

Install HERMES and dependencies

poetry comes with its own environment management. To create a development environment and install dependencies, run

# Create an environment dedicated to hermes development
poetry shell
# Install dependencies
poetry install

Which dependencies do we use?

Building a CLI application, we deliberately chose the Click framework to implement the different workflow parts as commands verbs.

To learn what other packages hermes depends on, have a look at the project configuration file pyproject.toml (in the root of the repository), or use poetry show --only main.

To show dependencies that are only required for active development, or for building documentation run poetry show --only dev and poetry show --only docs respectively.

Verify installation works

That’s it, you should now have a working development copy of HERMES in your environment. You can confirm this by running hermes --help to show available commands and options.

Verify tests can be run

Tests are implemented using pytest.

To run all tests, execute pytest test/ within the activated poetry environment.

To create an extensive test coverage report in HTML, execute:

poetry run pytest test --cov=hermes --cov-branch --cov-report=html --cov-report=term

Optional: Verify docs build

This project comes with extensive documentation that can be built using Sphinx. This also includes automatic API documentation. To build the documentation in your poetry environment, run the following commands from the project root:

poetry install --with docs
poetry run task docs-build

Or use sphinx-autobuild to enable a self-updating preview service:

poetry install --with docs
poetry run task docs-live