RAES Environment Packs

RAES environment packs give a scenario a standard shape. This package defines that shape and gives you the tools to build, check, and ship a pack.

A pack holds the declarative content for one reference environment: the scenario start state, its assets, and a record of where the content came from. Authors build packs; consumers validate a pack before they trust it. The format and the tools ship together, so you validate a pack against the same version you built it against.

This repository defines and validates the format. It does not host packs — those live in their own catalog repositories.

What a pack looks like

example-pack/
├── pack.yaml                  # identity: name, title, version, status
├── sdl/example.sdl.yaml       # the scenario start state (RAES SDL)
└── docs/
    └── provenance-ledger.yaml # where the content came from

The start state is small to begin with:

name: example-pack
nodes:
  target:
    type: vm

Install

pip install raes-env-packs

That installs four command-line tools and the importable library:

• raes-new-pack — scaffold a new pack from the bundled template.
• raes-pack-validate — the author-CI check for a catalog checkout.
• raes-pack-release — build, lint, and release-gate a pack.
• raes-pack-issue-skeleton — generate a pack's starter GitHub issues.

Validate your first pack

Scaffold a pack in your catalog repository, add a start state, and check it:

raes-new-pack example-pack --title "Example Pack" \
  --description "A tiny example environment pack." --issue 1
# add sdl/example.sdl.yaml (above) and set the pack name in
# docs/provenance-ledger.yaml, then:
python -c "from raes_env_packs import validate_pack; print(validate_pack('environments/example-pack').ok)"

True

validate_pack is the check a consumer runs before trusting a pack: it reads the staged files, returns a result, prints nothing, and never runs the pack's code. The quickstart walks through it step by step.

Choose your route

• Author a pack — start with the quickstart and the pack reference.
• Consume a pack — see validating a pack.
• Contribute — read CONTRIBUTING.md.

Full documentation is on Read the Docs.

What this is and is not

This project defines the pack format and the tools that check it. It does not host packs, run a scenario, or define scenario meaning — the RAES scenario language and its semantics belong to RAES, and this project consumes them from an exactly pinned raes release. It is a single-maintainer project with no support SLA. See the limitations for the full picture.

Contributing

python3 -m venv .venv
. .venv/bin/activate
pip install -e .
python -m unittest discover -s tests

CONTRIBUTING.md has the full setup, test, and submission path. Maintainer records — decision records, CI, and release mechanics — are indexed in docs/README.md.

Releases

Releases are managed by release-please: merge-driven, nothing hand-run. Your Conventional Commit PR title is the release decision — feat: is a minor bump, fix: a patch, docs:/chore: no release. You never edit the version or CHANGELOG.md; release-please owns both. See CONTRIBUTING.md for the details.

License

MIT — see LICENSE.