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.
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.
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/workflow.git cd workflow
All Python sources are in the
pytesttests are in the
Architectural Decision Records (ADR) are in
API documentation is automatically generated into
All other Sphinx-based documentation lives in
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.
mainbranch which only includes releases
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
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
(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.
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.
Tests are implemented using pytest.
To run all tests, execute
pytest test/ within the activated
To create an extensive test coverage report in HTML, execute:
poetry run pytest test --cov=hermes --cov-branch --cov-report=html --cov-report=term
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
sphinx-autobuild to enable a self-updating preview service:
poetry install --with docs poetry run task docs-live