HOWTO: Version a Pack and Promote It Across Environments¶

Purpose: Tag a pack with a semantic version and advance it through the full dev → staging → production promotion chain.

Difficulty: Advanced

Track: Contract-Driven Automation

Overview¶

A pack release formalises a set of modules, profiles, and blueprints as a coherent version that can be promoted as a unit. The promotion workflow enforces quality gates at each environment boundary: ensuring that only runs with sufficient run records and approvals advance to production. This HOWTO covers the complete lifecycle from first tag to production deployment.

1. Pack Structure and Versioning¶

Pack manifest: pack.yaml schema.
Semantic versioning conventions for packs.
Changelog requirements and how they feed the promotion report.

2. Tagging a Release¶

Creating a version tag in Git.
Pack validation with hyops pack validate.
Generating the release records.

3. Dev Promotion Gate¶

Required run records from dev environment.
Run-record thresholds: minimum passing steps, required record types.
Marking dev as promotion-ready.

4. Staging Promotion Gate¶

Staged smoke tests and their run-record outputs.
Policy assertion checks from the staging profile.
Manual sign-off workflow.

5. Production Promotion Gate¶

Production approval requirements.
Change window enforcement.
Promotion run record: linking pack version, approvals, and supporting records.

6. Version Pinning in Dependent Configs¶

How downstream modules pin to a pack version.
Updating pins across the config tree.
Rolling back a pack version.

References¶

License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.