Skip to main content

ADR-026: Registry & Versioning Strategy — GitHub Source + Unified Version

Status​

ACCEPTED — 2026-03-13. May reopen for public registry if HashiCorp adds monorepo support.

Supersedes: ADR-025 (Per-Component Semver) — unified versioning replaces per-module versioning for KISS/LEAN with 1 HITL + AI agent team.

Context​

The terraform-aws monorepo contains 12 modules. With 1 HITL manager and AI agents, maintaining 12 independent version tracks creates unnecessary cognitive overhead. All modules share the same Terraform/AWS provider constraints (ADR-003) and release cadence.

Decision​

1. Distribution: GitHub monorepo source (PRIMARY)​

module "sso" {
  source = "github.com/nnthanh101/terraform-aws//modules/sso?ref=v2.0.0"
}
module "ecs" {
  source = "github.com/nnthanh101/terraform-aws//modules/ecs?ref=v2.0.0"
}

Same ?ref=vX.Y.Z tag for ALL modules. Different //modules/<name> subpath.

Private registry (app.terraform.io/oceansoft/) retained as BACKUP.

2. Versioning: Unified root vX.Y.Z tag​

  • Single VERSION file at repo root (not per-module)
  • release-please configured as 1 root package (not 12)
  • Git tag format: v2.0.0, v2.1.0, etc. (root level, no prefix)
  • Any change to any module bumps the shared version
  • Starting at v2.0.0 (clean break from per-module era)

Rationale​

  1. 1 HITL: Tracking 12 versions is overhead with zero business value for internal consumption
  2. KISS/LEAN: 1 version, 1 tag, 1 changelog, 1 release
  3. Public registry compatible: Root vX.Y.Z tags are exactly what HashiCorp public registry expects — future migration path preserved
  4. Atomic releases: Cross-module changes (e.g., provider constraint bumps) are 1 commit, 1 tag
  5. Zero cost: No registry infrastructure needed

Trade-offs​

Accepted Trade-offWhy Acceptable
Unchanged modules get version bumps1 HITL doesn't need per-module granularity
Semver less meaningful per-moduleInternal consumers pin to tag, don't use semver ranges
Larger changelogsSingle CHANGELOG is easier to review than 12

Consequences​

  • VERSION at repo root = 2.0.0
  • Per-module VERSION files removed (12 deleted)
  • release-please-config.json: 1 root package replaces 12
  • .release-please-manifest.json: {".": "2.0.0"}
  • projects/sso/main.tf and projects/ecs/main.tf use ?ref=v2.0.0
  • CI validate-projects no longer requires TFE_TOKEN

Reopen Triggers​

  • Team grows beyond 1 HITL — per-module versioning may become valuable
  • Public registry adoption (requires multi-repo OR HashiCorp monorepo support)
  • External consumers need semver range constraints (~> 1.2)
  • OpenTofu registry proves monorepo tag-prefix support at scale
  • ADR-002: Registry Structure (superseded for primary distribution)
  • ADR-003: Provider Constraints (shared across all modules)
  • ADR-023: Derived Module Pattern (Apache 2.0 compliance)
  • ADR-025: Per-Component Semver (SUPERSEDED by this ADR)