mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 18:21:32 +00:00
shankar0123
0161bb201c
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.
46 lines
2.1 KiB
Bash
Executable File
46 lines
2.1 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# scripts/ci-guards/S-1-hardcoded-source-counts.sh
|
|
#
|
|
# S-1 master closed cat-s1-9ce1cbe26876 (README + features.md
|
|
# stale numeric counts; explicit violation of project guidelines per
|
|
# "version-stamped numbers rot") and
|
|
# cat-s1-features_md_issuer_count_contradiction (features.md
|
|
# self-disagreed on issuer count: 9 vs 12 in the same doc).
|
|
# The fix replaced source-derived numbers in prose with
|
|
# "rebuild via <command>" patterns documented in the project guidelines under
|
|
# "Current-state commands". This script grep-fails the build if
|
|
# any of the previously-stale sites reintroduces a hardcoded
|
|
# count.
|
|
#
|
|
# Allowed surfaces: demo-fixture prose in README ("32
|
|
# certificates" — those are seed_demo.sql facts, not live
|
|
# source counts), the testing-guide example phrasing
|
|
# ("README claims 8 issuer connectors but only 6 exist"),
|
|
# and any number that quotes the source command immediately
|
|
# adjacent.
|
|
#
|
|
# See coverage-gap-audit-2026-04-24-v5/unified-audit.md
|
|
# cat-s1-9ce1cbe26876 + cat-s1-features_md_issuer_count_contradiction
|
|
# for closure rationale.
|
|
|
|
set -e
|
|
BAD=$(grep -rnE '\b[0-9]+\s+(issuer connectors?|target connectors?|notifier connectors?|discovery connectors?|MCP tools|OpenAPI operations|migrations|database tables|frontend pages|HTTP routes)\b' \
|
|
README.md docs/ 2>/dev/null \
|
|
| grep -vE 'seed_demo|demo override' \
|
|
| grep -vE 'DRIFT HAZARD|Source: |Rebuild|rebuild via|grep -|wc -l|ls -d|find ' \
|
|
| grep -vE 'README claims [0-9]+ issuer connectors but only [0-9]+ exist' \
|
|
|| true)
|
|
if [ -n "$BAD" ]; then
|
|
echo "::error::S-1 regression: hardcoded source-count prose reappeared:"
|
|
echo "$BAD"
|
|
echo ""
|
|
echo "Project rule: 'Numeric claims about current state rot.'"
|
|
echo "Replace the count with the grep command documented under"
|
|
echo "'Current-state commands' (e.g. 'ls -d internal/connector/issuer/*/ | wc -l')"
|
|
echo "or rephrase to reference the rebuild command on the same line."
|
|
echo "See coverage-gap-audit-2026-04-24-v5/unified-audit.md"
|
|
echo "cat-s1-9ce1cbe26876 for closure rationale."
|
|
exit 1
|
|
fi
|
|
echo "S-1 hardcoded-source-counts: clean."
|