Skip to content

docs: reconcile 3 stale doc references post-v0.2.0 (closes #256 #257 #259)#263

Merged
trilamsr merged 3 commits into
mainfrom
docs/triage-doc-rot-batch
Jun 1, 2026
Merged

docs: reconcile 3 stale doc references post-v0.2.0 (closes #256 #257 #259)#263
trilamsr merged 3 commits into
mainfrom
docs/triage-doc-rot-batch

Conversation

@trilamsr

@trilamsr trilamsr commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Three concern-isolated doc-rot reconciles, one commit per issue:

Root causes

Sequencing note

PR #258 is the source of truth for the post-pivot inline-shell package job referenced by the #259 reconcile. #258 is currently open + green; if #258 merges first, the doc paths are immediately accurate. If this PR merges first, the docs describe the target state and converge once #258 lands. Either order works.

Test plan

  • bash scripts/doc-check.sh — clean (500 markdown links resolve, 47 non-.md intra-repo links resolve, banned-phrase lint clean, all required sections present, 10 fenced bash/sh blocks in docs/reproducibility.md shell-syntax-clean).
  • make check — clean (gofumpt, tidy-check, golangci-lint 0 issues, go vet, go mod verify).
  • Manual cross-link spot check: confirmed the new #222 issue links + docs/migration/v0.2-to-v0.3.md cross-references resolve; confirmed RFC (deferred to v0.4.0+ per #222) markers attached at every flagged line (matrix row, deletion-list rows, §Migration/rollout sequencing entry); confirmed reproducibility docs no longer mention goreleaser anywhere via grep -i goreleaser.
  • Verified no in-flight conflicts with PR docs(migration): reconcile v0.2-to-v0.3 with PR-M v0.4.0+ deferral #254 (already-merged migration-guide reconcile) or PR fix(release): replace goreleaser pro-only prebuilt builder with OSS-compatible shape #258 (still-open inline-shell pivot — touches .github/workflows/release.yml + deletes .goreleaser.yaml, no overlap with this PR's files).

Out of scope / follow-ups

No new doc-rot noticed beyond the three issues addressed here.

docs: reconcile three stale references post-v0.2.0: pyspy README + RUNBOOK + RFC-0013 §Migration now correctly reflect that PR-M (parca-agent recipe + pyspy delete) is deferred to v0.4.0+ pending OTel Profiles → Beta + parca-agent OTLP export (#222); reproducibility docs (docs/reproducibility.md + docs/notes/reproducibility.md) updated for the post-#258 inline-shell `package` job — operator-facing integrity chain (sha256sum → checksums.txt → cosign bundle → SLSA attestation) preserved end-to-end.

Closes #256.
Closes #257.
Closes #259.

Tri Lam added 3 commits May 31, 2026 20:26
Banner predates the PR-M deferral memo in #222 — pyspy ships as-is in v0.3.0 with unchanged zero-capability posture until OTel Profiles reaches Beta + parca-agent gains OTLP export. Reframe README + RUNBOOK status banners to name #222 as the source of truth for re-evaluation triggers; keep the CAP migration pointer to docs/migration/v0.2-to-v0.3.md as forward-looking material.
Add deferral banners at §4 Migration timeline (v0.3.0 row) and §Migration/rollout v0.3.0 sequencing. Annotate the §7 Deletion list rows (pyspy receiver + python/tracecore_pyspy + tools/pyspy-lint) and the PR-M sequencing entry with explicit '(deferred to v0.4.0+ per #222)' markers. Re-evaluation triggers (OTel Profiles → Beta + parca-agent OTLP export OR sibling-distro re-scope) named at the point of the stale claim, not just in cross-references. Historical sequencing preserved verbatim.

Signed-off-by: Tri Lam <tri@maydow.com>
PR #258 drops .goreleaser.yaml in favor of an inline-shell package job in .github/workflows/release.yml. Update docs/reproducibility.md + docs/notes/reproducibility.md to match:

- Drop all .goreleaser.yml / .goreleaser.yaml references (file deleted; the .yml extension was always typo'd — never existed).
- Drop signer-workflow references to the never-existed .github/workflows/goreleaser.yml; the actual file is .github/workflows/release.yml.
- Reframe the build narrative around the new deterministic-byte controls: SOURCE_DATE_EPOCH (tag commit timestamp) + tar --mtime + --sort=name + --owner=0 --group=0 --numeric-owner + gzip -n.
- Update download patterns + verification commands to operate on tar.gz archives (binary + LICENSE + README.md inside) rather than the prior bare binary.
- Per-archive CycloneDX SBOMs now follow tracecore_*_linux_amd64.tar.gz.sbom.cdx.json filename pairing; the canonical source-tree SBOM still comes from the sbom job.
- Add an explicit sha256sum -c checksums.txt step after download so the operator-facing integrity chain (sha256sum → checksums.txt → cosign bundle) is named in the walkthrough.
- Cosign bundle naming (tracecore_*.cosign.bundle, checksums.txt.cosign.bundle) is unchanged.

Signed-off-by: Tri Lam <tri@maydow.com>
@trilamsr trilamsr enabled auto-merge (squash) June 1, 2026 03:46
@trilamsr trilamsr merged commit 34e5a08 into main Jun 1, 2026
13 checks passed
@trilamsr trilamsr deleted the docs/triage-doc-rot-batch branch June 1, 2026 03:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant