🔍 Repository Review: Version Consistency & Documentation

[oldmanbendobot]

📋 Repository Review: terraform-null-context

Review Date: March 2, 2026
Reviewer: oldmanbendobot

Summary

This is a foundational module for context/naming consistency across the organization. It's well-structured with solid CI/CD, but has critical version consistency issues that need addressing before releasing a major version update.

---

⚠️ Critical Issues

1. Outdated Terraform Minimum Version Requirement

• Severity: HIGH
• Current: required_version = ">= 0.13" (from 2020)
• Issue: Version 0.13 is 5+ years old with significant language changes in 1.0+. This is unnecessarily permissive and conflicts with other repos in the org.
• Evidence:
  • terraform-null-label: >= 1.3
  • terraform-aws-lambda: >= 1.0.0
  • terraform-aws-tfstate (and others): >= 1.0+
• Fix: Upgrade to at least >= 1.3.0 to match terraform-null-label and drop support for deprecated versions. This is a breaking change requiring a major version bump.
• Impact: Inconsistent requirements confuse users and increase maintenance burden.

---

⚠️ High Priority Issues

2. Terraform Documentation Generation Disabled

• Severity: HIGH
• Current: .pre-commit-config.yaml has terraform-docs hook commented out
• Issue: README.md is manually maintained, but the module's variable and output blocks contain detailed descriptions that should be auto-generated into docs.
• Evidence: Line in .pre-commit-config.yaml (commented):

  #  - repo: https://github.com/terraform-docs/terraform-docs
  #    rev: v0.16.0

• Fix: Uncomment terraform-docs hook, regenerate README with latest version (check current: might be v0.18+)
• Related: Open issue 📝 Documentation: Add version pinning philosophy to README #156 about documentation

3. Missing Version Pinning Philosophy Documentation

• Severity: MEDIUM
• Current: Issue 📝 Documentation: Add version pinning philosophy to README #156 is open and unresolved
• Issue: The README should document why this module uses >= 0.13 (or the new version after fix) and when/how the minimum version will be bumped in the future.
• Fix: Add a "Version Pinning" or "Compatibility" section to README explaining semver strategy for this module.

---

🔧 Medium Priority Issues

4. Pre-commit Configuration Inconsistencies

• Severity: MEDIUM
• Issue: Pre-commit hooks vary across org repos. terraform-null-context uses:
  • gitleaks (v8.24.3)
  • pre-commit-hooks (v5.0.0)
  • golangci-lint (v2.1.2)
  • prettier (v4.0.0-alpha.8 — alpha version!)
• Problem: Some versions are frozen at old dates; prettier is on alpha (not recommended for stable code)
• Check: Verify prettier alpha is intentional. Consider using stable v4.0.0+ when available.
• Recommendation: Document version pinning rationale or use latest stable.

5. GitHub Actions Not Grouped

• Severity: LOW
• Issue: dependabot.yml uses groups for gomod and github-actions, but this module doesn't have terraform grouped separately.
• Check: The terraform group is properly configured, but confirm if this is intentional or can be combined.

---

✅ Positive Findings

• ✅ Test Coverage: Excellent terratest coverage with examples/complete and CI pipeline
• ✅ Security Policy: Proper SECURITY.md with 90-day disclosure timeline
• ✅ CI/CD Pipeline: Comprehensive GitHub Actions (test, lint, dependency-review, codeql, scorecard)
• ✅ Code Quality: tflint, trivy, golangci-lint all configured
• ✅ GPG Signed Commits: All recent commits are signed
• ✅ Go Module Health: Using recent Go 1.26 and terratest 0.56.0
• ✅ alexrc Configuration: Well-configured with intentional allow-list

---

🔍 Cross-Repo Consistency Findings

This module is a dependency for other org modules:

• Used by terraform-null-label for context propagation
• Should be stabilized before major versions are cut

Recommendation: Treat this as a foundational module and keep its semver version <= other modules that depend on it.

---

📝 Suggested Implementation Plan

Phase 1 (BREAKING):

1. Update versions.tf: required_version = ">= 1.3.0"
2. Uncomment and update terraform-docs pre-commit hook
3. Run terraform-docs to regenerate README (preserving manual sections)
4. Add "Version Pinning Philosophy" section to README
5. Release as major version (e.g., v1.0.0 if this was v0.x)

Phase 2 (Optional):

1. Verify prettier alpha version; upgrade to stable if available
2. Document pre-commit tool version rationale in CONTRIBUTING.md

---

🤔 Questions for Ben

1. Is Go 1.26 stable? (This is a future version; should we lock to 1.24-1.25?)
2. Should terraform-docs be restored, or was it intentionally disabled?
3. Is the alpha version of prettier (v4.0.0-alpha.8) intentional, or should it be stable?

---

Approval Status: Awaiting Ben's review and approval before implementation.

[bendoerr]

Approved

---

Is Go 1.26 stable? (This is a future version; should we lock to 1.24-1.25?)

Yes

---

Should terraform-docs be restored, or was it intentionally disabled?

Disabled

---

Is the alpha version of prettier (v4.0.0-alpha.8) intentional, or should it be stable?

Not sure