docs(migration): reconcile v0.2-to-v0.3 with PR-M v0.4.0+ deferral#254
Merged
Conversation
Signed-off-by: Tri Lam <tri@maydow.com>
This was referenced Jun 1, 2026
trilamsr
added a commit
that referenced
this pull request
Jun 1, 2026
…259) (#263) ## Summary Three concern-isolated doc-rot reconciles, one commit per issue: - **#256** — `components/receivers/pyspy/README.md` + `RUNBOOK.md` reframe the stale 2026-05-22 "Scheduled for deletion at v0.3.0" banner to "deferred to v0.4.0+ per [#222](#222)" with the OTel-Profiles-→-Beta + parca-agent-OTLP-export re-evaluation triggers named verbatim. - **#257** — `docs/rfcs/0013-distro-first-pivot.md` adds deferral banners at §4 Migration timeline (v0.3.0 row) and §Migration/rollout v0.3.0 sequencing; annotates the §7 Deletion list rows + PR-M sequencing entry with explicit `(deferred to v0.4.0+ per #222)` markers. Historical sequencing preserved verbatim (option 1 from the issue). - **#259** — `docs/reproducibility.md` + `docs/notes/reproducibility.md` reconciled against post-PR-#258 inline-shell `package` job: drop all `.goreleaser.yaml` / `.goreleaser.yml` / `goreleaser.yml` signer-workflow references; reframe build narrative around `SOURCE_DATE_EPOCH` + `tar --mtime` + `--sort=name` + `gzip -n` deterministic-byte controls; update download patterns + verification commands to operate on tar.gz archives; add an explicit `sha256sum -c checksums.txt` step so the operator integrity chain (sha256sum → checksums.txt → cosign bundle) is named in the walkthrough. Cosign bundle naming unchanged. ## Root causes - **#256**: banner predates the PR-M deferral memo in #222; PR #254 reconciled `docs/migration/v0.2-to-v0.3.md` but explicitly left the receiver READMEs out of scope. - **#257**: PR #254's References section flagged the RFC body with a "supersede with #222" note but the body itself was untouched. - **#259**: PR #258 (goreleaser → inline shell) deletes `.goreleaser.yaml`; the reproducibility docs additionally referenced a never-existed `.github/workflows/goreleaser.yml` signer-workflow path (the file has always been `release.yml`), so the docs were doubly-broken pre-#258 and singly-broken post-#258. ## 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 - [x] `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). - [x] `make check` — clean (gofumpt, tidy-check, golangci-lint 0 issues, go vet, go mod verify). - [x] 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`. - [x] Verified no in-flight conflicts with PR #254 (already-merged migration-guide reconcile) or PR #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. ```release-notes 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. --------- Signed-off-by: Tri Lam <tri@maydow.com> Co-authored-by: Tri Lam <tri@maydow.com>
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.
Summary
PR-N (
docs/migration/v0.2-to-v0.3.md) landed at #200 assuming PR-M (delete pyspy + shipparca-agentrecipe) would cut at v0.3.0, which made the CAP_SYS_PTRACE → CAP_SYS_ADMIN/CAP_BPF migration a v0.3.0 break. #222 subsequently deferred PR-M to v0.4.0+ (triggers: OTel Profiles → Beta + feature-gate removed AND parca-agent gains OTLP export). The migration doc now contradicts reality —components/receivers/pyspy/still ships in v0.3.0's OCB binary,tracecore-pyspystays on PyPI, and the chart'sreceivers.pyspy.*key is still honoured. This PR reframes the timeline throughout: pyspy STAYS in v0.3.0 with unchanged zero-capability posture, the CAP migration is preserved as forward-looking operator preparation material for v0.4.0+, and #222 is named as the source of truth for re-evaluation triggers. The CAP migration content itself (theparca-agentrequirements table, minimum-grant SecurityContext, failure-mode table, removal checklist) is retained because operators planning v0.4.0+ upgrades still need it; only the timeline framing changes.Test plan
make check— green (fmt, tidy-check, lint, vet, mod-verify).make doc-check— green (501 markdown links resolve, banned-phrase lint clean across 106 files, comment-noise diff gate clean vs origin/main, no rot-prone reference drift).Noticed but out-of-scope
components/receivers/pyspy/README.mdstill carries a 2026-05-22 banner saying the receiver is "Scheduled for deletion at v0.3.0 per RFC-0013 §7". Same staleness pattern as the migration doc, but kept out of this PR's scope per the reconcile-only contract. Worth a follow-up sweep that re-times the README + RUNBOOK banners against PR-M: parca-agent recipe + delete pyspy — DEFERRED to v0.4.0+ #222.Release notes