Verifying the MAMS Examples

The guide includes an executable checker, scripts/verify_mams_examples.py, and a GitLab CI configuration. They check that the downloadable projects match their source, compile successfully and behave as described. Java 17, Maven and Python 3 are required; source verification also requires Git. Run the commands below from the documentation repository root.

Verify the audited source

Clone MAMS and select the commit used by this guide:

git clone https://gitlab.com/mams-ucd/mams-cartago.git .verification/mams-checkout
git -C .verification/mams-checkout checkout --detach 280367ee634fdcf6a37a0f1c594eb97a2c4476c2
python3 scripts/verify_mams_examples.py --mams-source .verification/mams-checkout --repository .verification/source-repository

The checker verifies the commit, builds an archived copy of its source, runs the relevant MAMS module tests and installs those artifacts into the specified Maven repository. It then compiles all twelve guide projects and checks the eleven ZIP downloads against the checked-in files. The introductory project is provided as individual files.

Runtime checks cover item updates, active refusal, collection creation and deletion, the HTTP client, sums, ping-pong, HAL negotiation, Hydra discovery and JSON-LD writes, delivery outcomes the custom counter’s methods and headers, and the packaged Java launch. The checker starts and stops its own processes. Ports 9000 and 9001 must be free; stop other guide examples before running it.

Build copies and logs are kept under .verification/source/, with a JUnit report at .verification/source-results.xml. The downloadable source directories are not used as build output directories. A failing command reports the log path; HTTP assertions appear in the report. A failure produces a non-zero exit status.

Check published dependencies separately

Use a fresh Maven repository to check that the projects’ declared dependencies can be downloaded and compiled without installing MAMS from source:

python3 scripts/verify_mams_examples.py --compile-only --repository .verification/published-repository --work-dir .verification/published --report .verification/published-results.xml

Choose an unused repository directory for a cold dependency check. The checker does not delete an existing Maven repository. This check verifies dependency availability and compilation; it does not establish that published 2.4.1 artifacts contain the audited source commit.

Use --offline only after the selected repository already contains all required dependencies. --work-dir and --report allow separate verification runs to keep their outputs apart.

Checks in GitLab

The repository’s .gitlab-ci.yml defines three jobs:

Job	What it checks
`html-guide`	Builds the Sphinx website with documentation warnings treated as errors.
`mams-source-examples`	Builds the pinned MAMS source and runs archive, compilation and runtime checks.
`mams-published-dependencies`	Checks archives and compilation against independently downloaded published dependencies.

The Maven jobs use separate repositories and no dependency cache. They retain logs and JUnit reports, including on failure. GitLab displays the reports with the pipeline results; see the GitLab CI configuration reference.

These jobs validate changes; they do not publish the website or deploy a service. To audit a newer MAMS commit, update the source pin in the checker, CI configuration and deployment Dockerfile together, then review the guide against the new behavior and rerun the checks. When project source changes, regenerate its ZIP download before submitting the change.