From 68f1e82ae87863447527c95ba426c0e103f6f4ac Mon Sep 17 00:00:00 2001 From: Oleksandr Kuzminskyi Date: Sat, 15 Aug 2026 18:53:35 -0700 Subject: [PATCH] docs: warn that .terraform.lock.hcl corrupts terraform-docs README output When a lock file exists in the module root, terraform-docs writes resolved provider versions into README's Providers table instead of the constraints from terraform.tf, and the pre-commit hook silently stages the regenerated README during commit. Document the pitfall and the safe validation workflow in CODING_STANDARD.md. Co-Authored-By: Claude Fable 5 --- modules/plain-repo/files/CODING_STANDARD.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/modules/plain-repo/files/CODING_STANDARD.md b/modules/plain-repo/files/CODING_STANDARD.md index aeb60f6..812c926 100644 --- a/modules/plain-repo/files/CODING_STANDARD.md +++ b/modules/plain-repo/files/CODING_STANDARD.md @@ -390,6 +390,16 @@ This document defines coding standards for InfraHouse projects. * **terraform-docs configuration:** - `.terraform-docs.yml` is managed by github-control - README.md uses centrally-managed configuration +* **terraform-docs and `.terraform.lock.hcl` (CRITICAL):** + - Never leave `.terraform.lock.hcl` (or `.terraform/`) in the module root when committing + - When a lock file is present, terraform-docs writes **resolved** provider versions (e.g. `6.60.0`) + into README's Providers table instead of the constraints from `terraform.tf` (e.g. `>= 5.11, < 7.0.0`) + - The pre-commit hook regenerates README.md during `git commit` and silently stages the change, + so the committed diff can differ from the diff reviewed before committing + - If `terraform init` is needed to validate the module, run it in the test root + (e.g. `test_data//`, where init artifacts are gitignored and not read by terraform-docs) + instead of the module root, or delete `.terraform/` and `.terraform.lock.hcl` before committing + - After committing, verify with `git show --stat` that the commit contains only the intended changes ### GitHub Pages Documentation (terraform_module) * **Deployment:** Automated via `.github/workflows/docs.yml` (managed by github-control)