docs: validate the README + entire doc tree against the code (and fix 2 bugs it surfaced)#23
Merged
Merged
Conversation
…ch backends Two correctness bugs surfaced while validating the docs against the code: - restore: the post-restore --verify gate ran `pg_verifybackup <target>` without -n, so it tried to parse WAL. A pg_hardstorage restore lays down the base backup only (WAL is fetched at recovery via the restore_command), so the data dir has no pg_wal yet — pg_verifybackup failed EVERY normal restore with "could not find any WAL file", reporting `Verification: failed`. It now passes -n (--no-parse-wal), verifying the manifest + file checksums; a clean restore reports `Verification: passed`. - simple helper: validateRepoURL accepted `gs://` and `azure://` — schemes with no registered backend — and rejected the real `gcs://` / `azblob://`. It now matches the schemes the storage registry actually registers (file, s3, gcs, azblob, sftp, scp). Both covered by regression tests.
…al CLI Validated every command, flag, count, sample output, and file link in the README and the basic tutorials against the actual binary (captured real output from a live PostgreSQL) and fixed everything that did not match: - README: bare `make` prints help, it does not build — use `make build` (and `make all-binaries` for both binaries). Dropped "no incremental chains to break" (the tool ships PG 17 incremental backups / `--incremental-from`). - getting-started: replaced the entirely fabricated `doctor` output with the real sectioned report; the container section no longer tells users to `docker pull` an unpublished image (build from the Dockerfile); `hint:` not "Suggested fix:"; version-agnostic integration-test PG. - first-backup-restore: replaced fabricated backup / list / show / restore output blocks with real captured output; `show` no longer claims encryption-envelope / verification-record rows it does not print. - pitr: real "Restore plan (preview only …)" preview and "✓ Restore complete / Recovery armed" apply output; backup IDs include the hash. - encryption: real `kms inspect` format and keyring filenames; manifest field is `wrapped_dek` (+`scheme`), not `wrapped_dek_b64`; a denied KMS Decrypt is an auth error (exit 3), not `kms.unauthorized (exit 8)`; `kms rotate` is not approval-gated (only `kms shred` is; shred needs `--repo`). - patroni: real `patroni status` layout; real follower event ops (`wal.follower.leader_change` / `slot_reconciled` / `wal_gap_detected`); removed the unimplemented "≥5 TB prefers a replica" claim.
…version claims against the code Fixes surfaced by validating every claim against the v1.0.7 binary: - operator-guide: 'stub/deferred to v0.5' relabelled as shipped for wal push, verify --full, repo scrub, kms rotate, kms shred; config key keep_full_count -> keep_fulls. - cost/slo: replaced the fabricated by_tenant[] JSON shape and wrong jq field names (bytes_total -> total_bytes, rpo_target -> rpo_target_seconds) with the real body fields. - reference: keystore path, live metric catalogue, StoragePlugin Barrier method, local: KEKRef resolution, reserved-metric wording. - compliance/runbooks: removed the nonexistent 'rbac' CLI command from all four control mappings; gated --fips-strict behind the FIPS build; marked cross-region residency enforcement (--allow-cross-region) as roadmap; fixed runbook flags/codes (--out not -o, --force not --confirm, restore.target_in_wal_gap/exit 7, splitbrain.* codes, repair scrub --heal); reconciled control-plane-setup v0.4/v0.5 framing to shipped.
…t the code
- Tier-2 plugin transport is one-shot stdio JSON-RPC, not
hashicorp/go-plugin / gRPC (that is the v1.1 roadmap contract).
- Synchronous-target mode (wal_mode: synchronous) is not implemented —
only sync-standby detection ships; marked as roadmap.
- Real dual-slot config schema (patroni.slots {name, role}); manifest
kek_ref local:default; comparison doc no longer claims Azure/GCS/SFTP
are unshipped.
- Skill signing is roadmap (skills are unsigned YAML today); real
builtin skills (ask/explain/incident/restore) and skill commands;
audit-anchor cadence via schedule.audit_anchor; k8s-Job sandbox is
roadmap; kms rotate/shred/repair attestation flag corrections; shims
ship today (not v1.1).
… and config schema Validated every recipe against the v1.0.7 binary and captured real output: - Added required flags the examples omitted (kms shred/verify --repo --require-approval, hold purge-expired --yes). - Removed false 'ghcr image carries the compat shims' claims — images aren't published and the shims are source-only; recipes now build them from cmd/pg-hardstorage-* in a builder stage. - Corrected sink plugin names (datadog-events / splunk-hec / otel-events) and config keys; the config-file schema (map-keyed deployments, pg_connection, struct schedules, per-deployment repo, keep_fulls). - Replaced ~25 fabricated output blocks (repo init, deployment/sink add, notify list, rotate, approvals, residency, scrub/heal, verify, version) with real captured output, and fixed ~10 wrong error codes. - Windows: no --mode flag (UID-based), release ships only pg_hardstorage.exe; version is a one-line output; Go 1.26+.
…d fabricated output - Tier-2 plugin protocol is stdio JSON-RPC, not go-plugin/gRPC (faq, glossary, tutorials/index). - Storage schemes gcs:// / file:// (not gs:// / fs://); KEKRef local:default (not local-keyring://). - PG 15-18 supported (18 is first-class, not allow-failure); audit anchoring is self-hosted today with external Rekor on the roadmap; builtin ask skill version 1.0.0. - llm-incident-walkthrough: replaced fabricated wal-stream error, export-session output, and bundle contents with the real output and tar entries; added the missing incident tool. - build-a-storage-plugin: plugin list (doctor has no plugin section), Barrier in the 12-method interface, mem:// steps marked aspirational, removed '(Agent F)' placeholders.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Validates the README and the entire documentation tree against the actual v1.0.7 binary and code — capturing real command output where examples were shown — and fixes everything that did not match. Two things came back clean throughout: 0 dead links (1580 checked) and no nonexistent top-level commands. The prose and examples were another story.
Two real code bugs the doc validation surfaced (fixed + regression-tested)
--verifygate was broken on every normal restore. It ranpg_verifybackup <target>without-n, so it tried to parse WAL that a base-only restore (WAL fetched at recovery viarestore_command) doesn't have — failing with "could not find any WAL file" and reportingVerification: failedon healthy restores. Now passes-n; a clean restore reportsVerification: passed. This makes the docs' verification claims true.gs:///azure://) instead of the registeredgcs:///azblob://.Documentation fixes (~76 files)
Recurring false claims
hashicorp/go-plugin(gRPC over stdio) — real is one-shot stdio JSON-RPC (gRPC is the v1.1 roadmap contract).wal push,verify --full,repo scrub,kms rotate,kms shred, control-plane restore/verify dispatch,/metrics, PG-backed registry,repair scrub --heal.rbaccommand cited in all four compliance mappings (SOC2/ISO/HIPAA/FedRAMP).docker pull ghcr:v1.1shim images,-fipsimage, packaged shims) — images aren't published; shims are source-only.Wrong values — sink plugin names (
datadog-events/splunk-hec/otel-events), config keys (keep_fulls,pg_connection, map-keyed deployments), schemes (gcs:///file:///local:default), error codes (restore.target_in_wal_gapexit 7,splitbrain.*, severalverify.*), a fabricated--allow-cross-regionflag,--mode system, Go 1.19→1.26, PG "15+"→"15–18", Rekor "by default"→roadmap, skill_version 1.0.0, and unimplemented sync-target / k8s-Job / ≥5 TB-replica / "no incremental chains" claims → roadmap or corrected.~30 fabricated sample-output blocks (backup, list, show, restore, preview, doctor, kms inspect, repo init, deployment/sink add, notify list, rotate, approvals, residency, scrub/heal, verify, version, patroni status, export-session) → replaced with real captured output.
Validation
/tmp/pghs <cmd> --help; counts checked against code registries; sample output captured from a live PostgreSQL and against the real renderers.go build ./...green; the two code fixes carry regression tests (TestVerify_PassesNoParseWAL,TestValidateRepoURL_Schemes).Commits
fix(restore,simple)— the two code bugs + testsdocs— README + basic tutorials (real captured output)docs(ops,reference,compliance)docs(explanation)docs(how-to)docs(faq,glossary,tutorials)