mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-09 15:18:58 +00:00
shankar0123
b452013dd9
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).
94 lines
4.7 KiB
Markdown
94 lines
4.7 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
git push --delete origin v<version>
|
|
git tag -d v<version>
|
|
```
|
|
|
|
Investigate, fix, re-tag.
|
|
|
|
## Related docs
|
|
|
|
- [`docs/contributor/qa-prerequisites.md`](qa-prerequisites.md) — local stack prereqs
|
|
- [`docs/contributor/test-environment.md`](test-environment.md) — full local environment tutorial
|
|
- [`docs/contributor/gui-qa-checklist.md`](gui-qa-checklist.md) — GUI manual QA pass
|
|
- [`docs/contributor/testing-strategy.md`](testing-strategy.md) — what we test in CI vs deep-scan vs manual QA
|
|
- [`docs/contributor/ci-pipeline.md`](ci-pipeline.md) — CI shape and regression guards
|
|
- [`docs/operator/performance-baselines.md`](../operator/performance-baselines.md) — performance regression spot checks
|
|
- [`docs/operator/helm-deployment.md`](../operator/helm-deployment.md) — Helm install + verify
|
|
- [`docs/reference/release-verification.md`](../reference/release-verification.md) — Cosign / SLSA / SBOM verification procedure
|