mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 12:21:31 +00:00
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:
@@ -137,52 +137,6 @@ jobs:
|
||||
GITHUB_REPOSITORY: ${{ github.repository }}
|
||||
run: bash scripts/coverage-pr-comment.sh
|
||||
|
||||
# Bundle P / Strengthening #6 — QA-doc seed-count drift guard. Forces
|
||||
# every PR that adds a seed row to migrations/seed_demo.sql to keep
|
||||
# docs/contributor/qa-test-suite.md::Seed Data Reference in sync.
|
||||
#
|
||||
# Phase 5 of the 2026-05-04 docs overhaul (commit c64777f) deleted
|
||||
# docs/testing-guide.md (its content dispersed across the new
|
||||
# audience-organized doc tree); the previous QA-doc Part-count drift
|
||||
# guard tracked Part counts between testing-guide.md and the old
|
||||
# qa-test-guide.md headline. With testing-guide.md gone, that guard's
|
||||
# premise is dead and it has been removed. The seed-count drift class
|
||||
# is still live: qa-test-suite.md::Seed Data Reference enumerates
|
||||
# certs/issuers and seed_demo.sql is the source of truth.
|
||||
- name: QA-doc seed-count drift guard
|
||||
run: |
|
||||
set -e
|
||||
DOC=docs/contributor/qa-test-suite.md
|
||||
# Seed-cert count: agnostic to documented header format. The current
|
||||
# documented count lives in `### Certificates (32 total in ...` —
|
||||
# extract the first integer in that header.
|
||||
DOC_CERTS=$(grep -oE '### Certificates \([0-9]+' "$DOC" | grep -oE '[0-9]+' | head -1)
|
||||
# Authoritative count: unique mc-* IDs in seed_demo.sql.
|
||||
SEED_CERTS=$(grep -oE 'mc-[a-z0-9_-]+' migrations/seed_demo.sql | sort -u | wc -l | tr -d ' ')
|
||||
if [ -z "$DOC_CERTS" ]; then
|
||||
echo "::warning::Could not extract documented cert count from $DOC."
|
||||
echo " Skipping cert-count drift check (header format may have changed)."
|
||||
elif [ "$DOC_CERTS" != "$SEED_CERTS" ]; then
|
||||
echo "::error::DRIFT — $DOC says $DOC_CERTS certs; seed_demo.sql has $SEED_CERTS unique mc-* IDs."
|
||||
echo " Update $DOC::Seed Data Reference to match."
|
||||
exit 1
|
||||
fi
|
||||
# Issuers: seed-table count vs doc claim.
|
||||
DOC_ISS=$(grep -oE '### Issuers \([0-9]+' "$DOC" | grep -oE '[0-9]+' | head -1)
|
||||
# Authoritative: unique iss-* IDs (close enough proxy; the issuers
|
||||
# table count IS the unique-ID count for this prefix).
|
||||
SEED_ISS=$(grep -oE 'iss-[a-z0-9_-]+' migrations/seed_demo.sql | sort -u | wc -l | tr -d ' ')
|
||||
if [ -z "$DOC_ISS" ]; then
|
||||
echo "::warning::Could not extract documented issuer count."
|
||||
elif [ "$DOC_ISS" != "$SEED_ISS" ] && [ "$((SEED_ISS - DOC_ISS))" -gt 5 ]; then
|
||||
# Allow up to 5pp slack — iss-* IDs appear in audit_events and
|
||||
# other reference tables that aren't issuer-table rows. Drift
|
||||
# only flags when the spread grows large.
|
||||
echo "::error::DRIFT — $DOC says $DOC_ISS issuers; seed_demo.sql has $SEED_ISS unique iss-* IDs (spread > 5)."
|
||||
exit 1
|
||||
fi
|
||||
echo "QA-doc seed-count drift guard: clean."
|
||||
|
||||
# Bundle Q / I-001 closure — test-naming convention guard (informational).
|
||||
# The convention is `Test<Func>_<Scenario>_<ExpectedResult>`. This step
|
||||
# prints any non-conformant tests but does NOT fail the build until the
|
||||
@@ -199,9 +153,8 @@ jobs:
|
||||
# internal scenarios expressed via `t.Run` subtests. Requiring the
|
||||
# underscore-Scenario-Result triple repo-wide would mean renaming
|
||||
# 167 legitimate tests for no observable behavior change. The
|
||||
# Test<Func>_<Scenario>_<ExpectedResult> form remains documented as
|
||||
# the recommended pattern for parameterized scenarios in
|
||||
# docs/contributor/qa-test-suite.md, but is not gated.
|
||||
# Test<Func>_<Scenario>_<ExpectedResult> form remains the
|
||||
# recommended pattern for parameterized scenarios, but is not gated.
|
||||
- name: Regression guards (extracted to scripts/ci-guards/)
|
||||
# All named regression guards live at scripts/ci-guards/<id>.sh per
|
||||
# ci-pipeline-cleanup bundle Phase 1. Each guard is callable locally:
|
||||
|
||||
Reference in New Issue
Block a user