docs: remove internal engineering docs; docs must be tool- or story-relevant

Operator policy: docs in the public repo must help (a) a user
deploying certctl or (b) the product story. Internal engineering
process documentation belongs in cowork/ scratchpads or in git
commit history, not docs/.

Removed (docs/contributor/, 8 files, 2,323 lines):
  - release-sign-off.md         — internal release-day checklist
  - ci-pipeline.md              — what runs in CI (internal)
  - ci-guards.md                — what the guards are (internal)
  - testing-strategy.md         — internal testing strategy
  - qa-test-suite.md            — internal QA reference (445 lines)
  - qa-prerequisites.md         — internal QA setup
  - gui-qa-checklist.md         — manual GUI QA checklist
  - test-environment.md         — 1,103-line redundant with
                                  docs/getting-started/quickstart.md +
                                  docs/getting-started/advanced-demo.md

Removed supporting script:
  - scripts/qa-doc-seed-count.sh — CI guard for the deleted
                                   qa-test-suite.md seed-data table

Cross-reference cleanup:
  - README.md: dropped the Contributor audience row + footer
    pointer to docs/contributor/.
  - Makefile: dropped `verify-docs` target + qa-stats comment refs.
  - .github/workflows/ci.yml: dropped the QA-doc seed-count drift
    CI step + dead comment refs.
  - docs/reference/cli.md: repointed qa-prerequisites.md → quickstart.md.
  - docs/operator/performance-baselines.md: dropped ci-pipeline.md
    cross-ref.
  - scripts/ci-guards/README.md: dropped the 'Guards explicitly
    NOT here' section that referenced the deleted QA-doc guards.

G-3 env-docs-drift guard improvements (a real consequence: deleting
the contributor docs surfaced that some env vars only had a home
there). Refit the guard to the new doc topology:
  - Defined-scan widened from `config.go + cmd/*` to all of `cmd/ +
    internal/` (production code), excluding `*_test.go` — catches
    service-layer env vars like CERTCTL_STEPCA_ROOT_CERT and
    CERTCTL_ZEROSSL_EAB_URL that were previously invisible to the
    guard.
  - Docs-scan widened to include deploy/ENVIRONMENTS.md (the
    canonical env-var inventory table — should have been in scope
    from day one). Kept narrow to README + docs/ + deploy/helm/ +
    ENVIRONMENTS.md to avoid pulling in compose/test fixtures.
  - ALLOWED filter now applies to both DOCS_ONLY and CONFIG_ONLY
    directions, so dynamic per-profile dispatch surfaces
    (CERTCTL_SCEP_PROFILE_<NAME>_*, CERTCTL_EST_PROFILE_<NAME>_*,
    CERTCTL_QA_*) don't need static doc entries.
  - Added CERTCTL_SCEP_PROFILE_[A-Z_]+ and CERTCTL_EST_PROFILE_[A-Z_]+
    to ALLOWED for the same reason.

deploy/ENVIRONMENTS.md: added CERTCTL_ZEROSSL_EAB_URL row — real
operator override (overrides the ZeroSSL EAB-credentials endpoint;
read at internal/connector/issuer/acme/acme.go:372) that was
defined in Go source but never documented. G-3 caught it after the
defined-scan widened.

scripts/ci-guards/S-1-hardcoded-source-counts.sh: removed dead
WORKSPACE-CHANGELOG.md allowlist entry (the file was deleted in
the prior workspace cleanup).

Verified:
  All 35 scripts/ci-guards/*.sh green (FAIL=0).
  No remaining references to docs/contributor/ or qa-doc-seed-count
  in tracked files.
This commit is contained in:
shankar0123
2026-05-13 02:44:27 +00:00
parent 57b539c378
commit 0161bb201c
18 changed files with 29 additions and 2464 deletions
+18 -7
View File
@@ -24,14 +24,19 @@
# cat-g-* for closure rationale.
set -e
# Defined: config.go + agent + cli + mcp-server + server cmds + test fixtures + ACME DNS export
# Defined: any CERTCTL_* env-var name appearing in production Go sources
# (cmd/ + internal/, excluding *_test.go) plus the ACME DNS-01 script-
# export surface. Test files use `t.Setenv` on env-var names that aren't
# necessarily operator config; harness-only names should not flag.
{
grep -nE '"CERTCTL_[A-Z_]+"' internal/config/config.go | sed -E 's/.*"(CERTCTL_[A-Z_]+)".*/\1/'
grep -rhoE '"CERTCTL_[A-Z_]+"' cmd/agent/*.go cmd/cli/*.go cmd/mcp-server/*.go cmd/server/*.go 2>/dev/null | sed -E 's/"(CERTCTL_[A-Z_]+)"/\1/'
grep -rhoE 'CERTCTL_[A-Z_]+' deploy/test/qa_test.go internal/connector/issuer/acme/dns.go 2>/dev/null
grep -rhoE '"CERTCTL_[A-Z_]+"' --include='*.go' --exclude='*_test.go' cmd/ internal/ 2>/dev/null | sed -E 's/"(CERTCTL_[A-Z_]+)"/\1/'
grep -rhoE 'CERTCTL_[A-Z_]+' internal/connector/issuer/acme/dns.go 2>/dev/null
} | grep -E '^CERTCTL_' | sort -u > /tmp/g3-defined.txt
# Documented: README + docs + helm
grep -rhoE '\bCERTCTL_[A-Z_]+\b' README.md docs/ deploy/helm/ 2>/dev/null | sort -u > /tmp/g3-docs.txt
# Documented: README + docs + helm + deploy/ENVIRONMENTS.md.
# (ENVIRONMENTS.md is the canonical env-var inventory; the rest of
# deploy/ contains compose/test fixtures whose env-var mentions are
# implementation noise, not operator documentation.)
grep -rhoE '\bCERTCTL_[A-Z_]+\b' README.md docs/ deploy/helm/ deploy/ENVIRONMENTS.md 2>/dev/null | sort -u > /tmp/g3-docs.txt
# Allowlist of env vars documented as external integration contracts.
# Each entry justifies itself in one line; if you add to this list,
# add the justification.
@@ -59,6 +64,8 @@ CERTCTL_AUDIT_EXCLUDE_PATHS|
CERTCTL_TLS_|
CERTCTL_TLS_INSECURE_SKIP_VERIFY|
CERTCTL_SCEP_|
CERTCTL_SCEP_PROFILE_[A-Z_]+|
CERTCTL_EST_PROFILE_[A-Z_]+|
CERTCTL_SERVER_CA_BUNDLE_PATH|
CERTCTL_SERVER_TLS_INSECURE_SKIP_VERIFY|
CERTCTL_QA_[A-Z_]+|
@@ -89,7 +96,11 @@ CERTCTL_RATE_LIMIT_
# the documented external contracts here.
ALLOWED_FLAT=$(echo "$ALLOWED" | tr -d '\n ')
DOCS_ONLY=$(comm -13 /tmp/g3-defined.txt /tmp/g3-docs.txt | grep -vE "$ALLOWED_FLAT" || true)
CONFIG_ONLY=$(comm -23 /tmp/g3-defined.txt /tmp/g3-docs.txt || true)
# Apply the same allowlist to the CONFIG_ONLY direction so dynamic
# per-profile dispatch surfaces (CERTCTL_SCEP_PROFILE_<NAME>_*, etc.)
# aren't flagged as "defined but never documented" — they can't all
# be enumerated in a static doc.
CONFIG_ONLY=$(comm -23 /tmp/g3-defined.txt /tmp/g3-docs.txt | grep -vE "$ALLOWED_FLAT" || true)
if [ -n "$DOCS_ONLY" ]; then
echo "::error::G-3 regression: env var(s) mentioned in docs but not defined in Go source AND not in the documented integration-surface allowlist:"
echo "$DOCS_ONLY"