docs(pivot): PR-H — PRINCIPLES + CONTRIBUTING pivot alignment#183
Merged
Conversation
Sweeps two top-level docs for RFC-0013 distribution-first drift per PR-H scope (docs/rfcs/0013-distro-first-pivot.md §migration). PRINCIPLES.md §2 (Reversibility before optionality) - Delete stale concrete example. The claim "we deferred GoReleaser, SBOM signing, Helm chart, OTel pdata import — none has cost us" is now factually wrong: PR-C landed goreleaser + SBOM + cosign stack, M5b shipped the Helm chart, and OCB adoption brings pdata in via upstream. The principle itself stands; the example was the contradictory bit. Delete > rewrite per no-bloat. CONTRIBUTING.md §Upstream-contribution-policy + §RFC-routing - `tracecoreai/tracecore-components` (external repo) → in-repo `module/` Go submodule per PR #181 rescope. Three references updated (intro paragraph, routing block, plus a third in the forthcoming-component-templates pointer that the next change deletes wholesale). CONTRIBUTING.md §Adding-a-component - Collapse ~130 lines of in-tree component tutorial down to ~10 lines of routing. The deleted content taught contributors to add receivers under `components/` referencing clockreceiver / dcgm / kernelevents as canonical shapes — all three are queued for v0.1.0 or v0.2.0 deletion per RFC-0013 §7, and the routing block 100 lines above already says "no new in-tree receivers." The step-by-step contradicted live policy with deleted-receiver examples; the receiver-shapes table pointed at a non-existent `tracecoreai/tracecore-components` repo. Replaced with the three actual routing branches (upstream first / moat → module/ / RFC for fifth-scope) plus a one-liner on the surviving factory shape. Scope notes: - PRINCIPLES.md §16 already cites RFC-0013 — no other edit needed. - CONTRIBUTING.md `clockreceiver` references (lines 139, 142, 149, 152 pre-edit) all resolved by deletion of their containing section, not by name-swap. Grep verified zero remaining `clockreceiver` or `tracecoreai/tracecore-components` mentions in the two files. - `make check` + `make doc-check` clean (505 markdown links resolve; cross-links to #upstream-contribution-policy + #rfc-process valid). - Skipped per prompt scope: MILESTONES.md / CHANGELOG.md (historic deletion tables) and docs/STRATEGY.md (out of scope for PR-H). Signed-off-by: Tri Lam <tri@maydow.com>
4 tasks
trilamsr
added a commit
that referenced
this pull request
May 31, 2026
## Summary Reconcile the four pivot-tracking docs (`docs/rfcs/0013-distro-first-pivot.md`, `CHANGELOG.md`, `MILESTONES.md`, `docs/migration/v0.1-to-v0.2.md`) with the wave-3 (PR-B1-shape sibling ports) and wave-4 (PR-B2-shape upstream-only ports + PR-F.1 + PR-J + PR-L + PR-N) landings. Pure doc sweep — no code or config touched. ## What changed ### `docs/rfcs/0013-distro-first-pivot.md` §migration PR sequence rows updated with PR-number citations and landed markers: - **PR-A2** (landed, #189, 2026-05-30) - **PR-B2** (landed, #201) — also enumerates sibling-receiver follow-ups under PR-B2 to dispel the slug collision with #188's PR-B2-labelled dcgm port: stdoutexporter (#202), pyspy (#203), kernelevents (#208), containerstdout (#209) - **PR-F.1** (landed) — fleshed-out delete list (`internal/{selftelemetry,telemetry}` + `components/receivers/dcgm/` + `pkg/dcgm/` + one orphan clockreceiver integration test) - **PR-F.2** re-scoped — now deletes the whole `internal/{componentstatus,pipeline,pipelinebuilder,consumer,fanout,runtime/lifecycle}` bundle in one cut once the last three pipeline+consumer-importing receivers land (#204 k8sevents, #205 clockreceiver, #207 otlphttp). Per the import-graph state — `internal/componentstatus`'s only non-test consumer is `internal/pipeline`, so they delete together - **PR-G** (landed, #182), **PR-H** (landed, #183) - **PR-I.1a** (in flight — scaffold agent), **PR-I.1b** (pre-staged; gate satisfied by #201) - **PR-J** (landed, #195) — kept existing marker - **PR-K.1** (in flight — separate agent landing) - **PR-L** (landed, skeleton #179 + body #191) — flagged as living document - **PR-N** (landed, #200) — shipped at v0.1.0 ahead of v0.3.0 as a doc-only update at `docs/migration/v0.2-to-v0.3.md` ### `CHANGELOG.md` [Unreleased] - Restructured the pivot wave list as **four waves** (was three). Wave 3 enumerates PR-B1-shape sibling ports + support infra (#180-#194/#196). Wave 4 enumerates PR-B2-shape upstream-only ports + PR-J (#195) + PR-F.1 (#206) + PR-N (#200) + lint/TOCTOU hardening (#198/#210). - Tightened the PR-F.2 deferred note to point at the three open ports (#204/#205/#207) as the gate. ### `MILESTONES.md` - **M1** (pipeline runtime) — status row now cites PR-A2 (#189), PR-F.1 (#206), PR-F.2 gate (#204/#205/#207), PR-E (#180), retains `internal/config/` (still load-bearing for `tracecore validate`). - **M2** (self-telemetry) — status row now cites PR-F.1 (#206); flags `internal/componentstatus` as travelling with `internal/pipeline` in PR-F.2. - **M8** (DCGM receiver) — status flipped to *landed-and-replaced*: cites PR-F.1 (#206) deletion + PR-J (#195) `docs/integrations/prometheus-scrape.md` recipe. Notes the inert chart toggle retention until PR-K.3. ### `docs/migration/v0.1-to-v0.2.md` - §`internal/*` package deletion (PR-F) status flips from "not yet open" to "PR-F.1 landed (#206), PR-F.2 gated on three open ports". - Open-items checklist expanded from 5 to 13 entries — tracks every PR letter the migration guide cares about (A2 / E / F.1 / F.2 / I.1a-c / J / K.1-3 / L / N) with PR numbers and links. ## Why now Tracking docs accumulated drift across wave-3 + wave-4 because every sibling-port PR (and the support-infra PRs around them) updated the bottom of `CHANGELOG.md` but did not always touch the upstream sequencing section in RFC-0013. Per memory rule `[Keeping this document current]`: status drift is a review blocker. This PR is the consolidated catch-up; future port PRs include their RFC-row flip in-PR. ## What this PR does NOT change - No code, no config, no YAML, no chart — only the four tracking docs. - No new doc gates added; existing gates pass. - No PRs other than the four named docs are modified. ## Test plan - [x] `bash scripts/doc-check.sh` clean (33 test refs, 528 links resolve, comment-noise diff gate clean vs `origin/main`, all 13 gates green). - [x] Pre-commit hook (`commitlint` 72-char subject limit + DCO + AI-trailer gates) passed. - [x] Pre-push hook (`make ci-fast` equivalent: `golangci-lint`, `go vet`, `go mod verify`, `no-autoupdate-check`, `doc-check.sh`) passed on second attempt after `git fetch origin main` populated the worktree's `origin/main` ref — first push failed because the worktree previously tracked the (gone) `pr-a2-ocb-main-swap` branch, so `doc-check.sh`'s comment-noise diff-scope gate exited 128 on the missing ref. Root cause fixed by the fetch; not a workaround. - [ ] CI green on this branch. ```release-notes NONE ``` Signed-off-by: Tri Lam <tri@maydow.com> Co-authored-by: Tri Lam <tri@maydow.com>
6 tasks
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-H sliver per RFC-0013 §migration. Sweeps
PRINCIPLES.md+CONTRIBUTING.mdfor distribution-first pivot drift. Net -128 lines.Root cause
Two unrelated drift accumulations, both fixed at source:
PRINCIPLES.md §2 example was factually wrong. The text "we deferred GoReleaser, SBOM signing, eBPF integration, the Helm chart, the OTel
pdataimport — none has cost us" predates the work that landed since: PR-C (chore(pivot): wave 1 — release + docs alignment + PR-E blocker #174) shipped the goreleaser + SBOM + cosign stack; M5b shipped the Helm chart; OCB adoption (feat(ocb): add builder-config + build-ocb target (RFC-0013 PR-A) #171 PR-A) pullspdatain via upstream. The illustrative example for "default to not adding" was listing items we did add. Deleted the example; the principle's first paragraph + bullet list above it carry the message without the contradiction.CONTRIBUTING.md carried two layers of pivot drift.
tracecoreai/tracecore-components(separate-repo framing) survived the PR docs(pivot): RFC-0013 §migration rescope — PR-I in-repo submodule #181 rescope to in-repomodule/Go submodule. Updated togithub.com/tracecoreai/tracecore/modulewith layoutmodule/receiver/<name>/,module/processor/<name>/.components/referencingclockreceiver/dcgm/kerneleventsas canonical shapes — but RFC-0013 §6 forbids new in-tree components ("Nothing else is built in-house"), and all three canonical references are queued for v0.1.0 or v0.2.0 deletion per §7. The routing block 100 lines above already declared the forbidding policy, so the tutorial was a live-policy contradiction with deleted-receiver examples. Replaced with a ~10-line routing block covering the three actual branches (upstream first / moat →module// RFC for fifth scope) plus a one-liner on the surviving factory shape. This is also why the four explicitclockreceiverreferences (lines 139/142/149/152 pre-edit) were resolved by deletion-of-containing-section rather than name-swap: no candidate survivor exists (dcgmdeletes v0.1.0,clockreceiver/kernelevents/k8sevents/containerstdoutdelete v0.2.0,nccl_fris logs-only and moves out tomodule/in PR-I.1).Changes
PRINCIPLES.md— delete one stale concrete-example paragraph (3 lines net).CONTRIBUTING.md—tracecoreai/tracecore-components→ in-repomodule/.Scope-discipline notes
Per prompt scope-fence:
MILESTONES.md/CHANGELOG.mddeletion-table drift untouched (historic / intentional per prompt).docs/STRATEGY.mduntouched (out of scope per prompt).PRINCIPLES.md§16 already cites RFC-0013 — no additional edit needed.STYLE.mdlines 106/115 referenceclockreceiveras a Go-import example; left in place — code example forpackage clockreceiverimport-form is shape-illustrative (will rotate when source actually deletes in PR-K). Flagged for the next sweep, not PR-H.cmd/tracecore/,bench/install/,install/kubernetes/,AGENTS.md,tools/components-gen/all carryclockreceiverreferences and are explicitly out of PR-H scope — those migrations land in PR-K (test-fixture coordination) per CHANGELOG line 16.Test plan
make check— clean (golangci-lint 0 issues, vet clean, mod-verify ok).make doc-check— clean (505 markdown links resolve including new#upstream-contribution-policy+#rfc-processcross-links; banned-phrase lint clean across 109 markdown files).make ci(via pre-push hook) — clean (actionlint + zizmor + alert-check + chart-appversion-check + no-autoupdate-check + clean-tree all pass).grep -n "clockreceiver\|tracecore-components" CONTRIBUTING.md PRINCIPLES.md— zero hits post-edit.#upstream-contribution-policyresolves to## Upstream contribution policy(L15);#rfc-processresolves to### RFC process(L39).Doc-only diff; no Go test corpus changes.