mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 17:02:43 +00:00

Files

T

shankar0123 b452013dd9 docs: Phase 5 — testing-guide.md prune (8268 → 0 lines, content dispersed)

Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/
and the section-by-section plan in testing-guide-tumor.md.

testing-guide.md was 30% of all docs/ content (8268 lines) but was
integration test code written in markdown, not operator documentation.
The audit's tumor analysis disposed of every Part:
  - ~65% DELETE (test cases that already exist in code)
  - ~22% MOVE to inline test code
  - ~8% KEEP-COMPRESSED into focused operator-runbook docs
  - Title + contents + release sign-off ~5% KEEP

This commit ships the KEEP-COMPRESSED dispersal:

  docs/contributor/qa-prerequisites.md (NEW, ~120 lines):
    From testing-guide.md "Prerequisites" section. Stack boot procedure,
    demo data baseline, reference IDs operators reuse across QA docs.

  docs/contributor/gui-qa-checklist.md (NEW, ~105 lines):
    From testing-guide.md "Part 35: GUI Testing". Manual GUI verification
    pass for release sign-off. 25-row table covering every dashboard page.

  docs/contributor/release-sign-off.md (NEW, ~130 lines):
    From testing-guide.md "Release Sign-Off" section (originally 1009
    lines of per-test detail tables). Compressed to a release-day
    checklist organized by gate category: code state, automated gates,
    manual QA passes, release artefact verification, branch protection,
    post-release.

  docs/operator/performance-baselines.md (NEW, ~100 lines):
    From testing-guide.md "Part 39: Performance Spot Checks". Four
    operator-runnable benchmarks (API request handling, inventory list
    pagination, scheduler tick, bulk revoke) with baseline numbers and
    when-to-re-baseline guidance.

  docs/operator/helm-deployment.md (NEW, ~120 lines):
    From testing-guide.md "Part 52: Helm Chart Deployment". Operator
    runbook for the bundled deploy/helm/certctl/ chart: prereqs,
    install, four cert-source patterns, verify, upgrade, troubleshooting.

  docs/reference/cli.md (NEW, ~120 lines):
    From testing-guide.md "Part 28: CLI Tool". certctl-cli command
    reference with command-group breakdown, common workflows
    (list/filter, renew, revoke, bulk import, EST enrollment, status),
    output formats, CI/CD integration patterns.

docs/README.md navigation index updated to include the 6 new docs:
  Reference section gains: cli.md, release-verification.md (was added
    in Phase 13)
  Operator section gains: helm-deployment.md, performance-baselines.md
  Contributor section gains: qa-prerequisites.md, gui-qa-checklist.md,
    release-sign-off.md

docs/testing-guide.md deleted. Git history preserves the 8268 lines —
if any specific test case is found missing from inline test code or
the destination docs during future work, lift from `git show
HEAD~1:docs/testing-guide.md`.

Net: docs/ total line count drops by ~7700 lines (28%), from 26,369
to 18,742. testing-guide.md was the single largest doc; pruning it is
the single biggest content-edit win of the entire restructure.

Phase 5 is the last major content phase. Remaining: Phase 4 follow-on
(per-connector page extractions from reference/connectors/index.md),
Phase 15 (WHAT/HOW/WHY remediation), Phase 16 (final acceptance gate).

2026-05-05 03:38:54 +00:00

4.7 KiB

Raw Blame History

Release Sign-Off

Last reviewed: 2026-05-05

Release-day checklist for tagging a new certctl release. Walks through the gates that must be green before pushing the tag, in the order they should be verified.

Pre-release: code state

Gate	How to check	Pass
`master` is at the commit you intend to tag	`git log -1 --format='%H %s'`	☐
Working tree clean	`git status -sb`	☐
Local matches GitHub	`curl -sS https://api.github.com/repos/certctl-io/certctl/commits/master \| grep -oE '"sha": "[a-f0-9]+"' \| head -1` matches local	☐
`WORKSPACE-CHANGELOG.md` updated with the release's milestones	manual review	☐
`certctl/CHANGELOG.md` updated (release-facing)	manual review	☐
Migration ladder ends cleanly	`ls migrations/*.up.sql \| sort \| tail -3` shows the right last migration	☐

Pre-release: automated gates (CI)

Gate	How to check	Pass
CI pipeline green on the tag-target commit	GitHub Actions web UI	☐
`make verify` clean locally	run from repo root	☐
`go test -race -count=1 ./...` clean	full race check	☐
`golangci-lint run ./...` clean	local lint	☐
`govulncheck ./...` clean	vulnerability scan	☐
Coverage thresholds met (service ≥55%, handler ≥60%, domain ≥40%, middleware ≥30%)	`go test -coverprofile=cover.out ./... && go tool cover -func=cover.out`	☐
Frontend type-check + Vitest + Vite build clean	`cd web && npm run typecheck && npm run test && npm run build`	☐

Pre-release: manual QA passes

Surface	Checklist	Pass
Local stack boots clean from scratch	`qa-prerequisites.md` Steps 1-4 green	☐
GUI QA checklist	`gui-qa-checklist.md` end to end	☐
End-to-end test environment	`test-environment.md` Steps 1-14 green	☐
Performance baselines	`performance-baselines.md` four spot checks within bounds	☐
Helm chart deploys clean	`helm-deployment.md` install + verify	☐
ACME server interop (cert-manager)	`make acme-cert-manager-test` green	☐
ACME server RFC conformance (lego)	`make acme-rfc-conformance-test` green	☐

Release artefact verification

After the release workflow runs (triggered by tag push), verify the published artefacts:

Artefact	How to verify	Pass
Cosign keyless OIDC signature on `checksums.txt`	per `docs/reference/release-verification.md` step 2	☐
SLSA Level 3 provenance on each binary	step 3	☐
Container image signature + SBOM + provenance	step 4	☐
Release notes published on GitHub Releases page	manual review	☐
ghcr.io images at `ghcr.io/certctl-io/certctl-{server,agent}:<tag>` pullable	`docker pull` round-trips	☐

Branch protection + tag push

Gate	How to check	Pass
`master` branch protection rule allows the tag push	Repository Settings → Branches	☐
Tag pushed	`git tag -s v<version> -m 'Release v<version>'; git push origin v<version>`	☐
Release workflow kicked off in GitHub Actions	watch the Actions tab	☐

Post-release

Gate	How to check	Pass
Release workflow completed without errors	GitHub Actions	☐
Sample binary downloaded and Cosign-verified by an operator who is not the release author	another team member	☐
`WORKSPACE-CHANGELOG.md` notes the tag commit SHA	manual edit	☐
`cowork/CLAUDE.md` "Active Focus" → "Current tag" updated	manual edit	☐
`certctl.io/index.html` star count + `data-gh-version` rendering picks up the new tag	open the landing page in 6+ hours (cache TTL)	☐
Reddit / Hacker News / LinkedIn announcement drafted (if a major release)	per the operator's promotion playbook	☐

If a gate fails

Revert the tag push immediately:

git push --delete origin v<version>
git tag -d v<version>

Investigate, fix, re-tag.

docs/contributor/qa-prerequisites.md — local stack prereqs
docs/contributor/test-environment.md — full local environment tutorial
docs/contributor/gui-qa-checklist.md — GUI manual QA pass
docs/contributor/testing-strategy.md — what we test in CI vs deep-scan vs manual QA
docs/contributor/ci-pipeline.md — CI shape and regression guards
docs/operator/performance-baselines.md — performance regression spot checks
docs/operator/helm-deployment.md — Helm install + verify
docs/reference/release-verification.md — Cosign / SLSA / SBOM verification procedure

4.7 KiB Raw Blame History