Skip to content

Hermesbaby 2. Constraints

2. Constraints¶

Constraints limit the solution space for HermesBaby's architecture and implementation. They are not open for negotiation within the project.

2.1. Technical Constraints¶

Constraint	Background
Python 3 runtime required on every host that runs HermesBaby	HermesBaby is distributed as a Python package. A compatible Python 3 interpreter must be available on the workstation, devcontainer, or CI runner. The exact minimum version is declared in `pyproject.toml`.
Sphinx and MyST-Parser are the document rendering engine	HermesBaby delegates all source-to-HTML/PDF conversion to Sphinx. MyST-Parser extends Sphinx to accept MyST Markdown source files. Both are mandatory runtime dependencies with their own release cycles, which can introduce breaking changes.
PlantUML requires a Java Runtime Environment on the build host	Sequence diagrams and other UML diagrams are authored as `.puml` files and rendered by PlantUML. PlantUML is a Java application; a JRE must be present. This adds a non-Python dependency to every build host.
draw.io CLI required for block diagram rendering	Block diagrams are authored as `.drawio` files. Rendering them during the documentation build requires the draw.io desktop application or its headless CLI equivalent to be installed separately from Python dependencies.
Git executable required on build hosts that inject metadata	HermesBaby injects build-time metadata (commit hash, branch name, tags) from the local Git repository into the generated documentation. The `git` executable must be available and the working directory must be inside a Git repository.
SSH client and configured key required for `hb publish`	Publishing transfers artefacts to a remote host via SCP/SSH. A compatible SSH client and a private key file must be present and configured in `.hermesbaby` before publishing can succeed.
Windows 10+ and Linux (Debian/Ubuntu) are the supported operating systems	HermesBaby is tested on these two platforms. macOS may work but is not an officially supported target. CI runners are assumed to be Linux-based.
Build must succeed without internet access after initial dependency installation	Engineering organisations often run CI in restricted or air-gapped networks. After `pip install hermesbaby` and its dependencies, all build operations must complete offline.

2.2. Organisational Constraints¶

Constraint	Background
Distributed as a pip-installable PyPI package	Installation must work with `pip install hermesbaby` and no additional package managers. This is the only distribution channel for end users.
Open source; all dependencies must have compatible licences	HermesBaby is published under an open-source licence. Every dependency must carry a licence that is compatible with this. Proprietary or copyleft-only dependencies are not permitted.
Source code and issue tracking hosted on GitHub	Repository, issue tracking, pull requests, and CI/CD pipelines all run on GitHub. Contributions follow the standard GitHub pull-request workflow.
No breaking changes to the CLI or `.hermesbaby` format without a MAJOR version bump	Engineering teams embed `hb` commands in CI scripts and commit `.hermesbaby` files to repositories. Breaking these without a clear version signal would silently break downstream projects.
No dependency on proprietary or commercial tool licences for reading, reviewing, or building	Regulated engineering mandates traceability, auditability, and rigor — not specific tools [MW26]. Every part of the HermesBaby workflow must be accessible with free, open-source tools. No contributor or reviewer should need a commercial licence to open, diff, or review any documentation artefact.

2.3. Conventions¶

Convention	Background
`.hermesbaby` uses Kconfig syntax for project configuration	All project metadata, build paths, publishing targets, and styling settings live in a single `.hermesbaby` file using Linux-kernel-style Kconfig syntax. Alternative configuration formats are not supported.
Documentation source files are authored in MyST Markdown	All user-facing documentation content is written in `.md` files using MyST Markdown directives. Pure reStructuredText (`.rst`) source files are not a supported authoring target.
Block diagrams are DrawIO files; sequence diagrams are PlantUML files	`.drawio` files are used for context, container, and component diagrams. `.puml` files are used for sequence, dynamic, and UML diagrams. This split follows the CLAUDE.md authoring conventions for this document.
Semantic versioning (MAJOR.MINOR.PATCH)	HermesBaby releases follow semantic versioning. A MAJOR bump signals breaking changes in the CLI interface or `.hermesbaby` configuration format.