IaC Module Registry & Versioning Strategy Prompt

You are a senior platform engineer responsible for a private IaC module registry that dozens of
teams depend on, and you protect them from breaking changes for a living.

I will provide:
- The registry/tooling in use ([Terraform/OpenTofu registry, Pulumi packages, Bicep ACR, npm for cdk
  constructs, a Git-tag scheme, etc.]).
- The modules in scope and roughly how many consumers each has.
- Our current versioning practice (or lack of one).

Your job:

1. **Define a semver contract** — state explicitly what counts as MAJOR (breaking input/output/behavior),
   MINOR (additive), and PATCH for THIS kind of module, with concrete examples of each.
2. **Set a consumer pinning policy** — recommend how consumers should constrain versions (e.g. pessimistic
   `~>`, exact pins, or ranges) and why, balancing safety against upgrade fatigue.
3. **Design the release flow** — tag/publish steps, a changelog requirement, and a rule that any input
   rename or output removal forces a major bump (never a sneaky minor).
4. **Plan deprecation** — how to deprecate an input or module: warning period, overlap release where old
   and new both work, and a migration note.
5. **Add automated guards** — a CI check that diffs the module's public interface (inputs/outputs) between
   versions and fails if a breaking change ships without a major bump.
6. **Document the upgrade path** — a template migration guide consumers follow for a major bump.

Output as: (a) the semver policy with examples, (b) the pinning recommendation, (c) the release/CI flow,
(d) a deprecation playbook, (e) a migration-guide template.

This is policy and process design, not a deploy. Recommend rolling any new versioning rule out behind a
human-reviewed RFC so existing consumers aren't surprised.

Why this prompt works

A module registry without a versioning contract is a slow-motion incident generator. The moment more than a handful of teams consume a shared module, the failure mode shifts from “does this module work” to “did this release break the forty teams who depend on it.” The root cause is almost always the same: a breaking change — an input renamed, an output removed, a default flipped — shipped as a minor or patch version, so every consumer inherited it on their next apply with no warning. This prompt makes the semver contract the first deliverable and demands concrete examples of MAJOR/MINOR/PATCH for this specific module type, because “breaking” means something different for a networking module than for a tagging helper.

The interface-diff CI guard is the highest-leverage item in the output. Humans forget to bump major versions; a CI check that mechanically diffs the module’s public inputs and outputs between versions and fails the release when a breaking change ships without a major bump removes the discipline from the human and puts it in the pipeline. That single control is what makes the rest of the policy enforceable rather than aspirational. The pinning policy is its consumer-side counterpart — pessimistic constraints let consumers pick up patches automatically while never being surprised by a major.

The deprecation playbook and migration-guide template address the part teams always skip: how to retire something gracefully. An overlap release where old and new inputs both work, plus a clear warning period, is the difference between a respected platform and one teams route around. Treating this as RFC-gated process design rather than a deploy keeps the existing consumers from being blindsided by the very policy meant to protect them. Pair with the reusable module design prompt and the Bicep ACR publishing prompt, and see the IaC category for more registry tooling.