feat(pipe): add version compatibility matrix automation (tracer pilot) - #1752
Open
gauchito91 wants to merge 10 commits into
Open
feat(pipe): add version compatibility matrix automation (tracer pilot)#1752gauchito91 wants to merge 10 commits into
gauchito91 wants to merge 10 commits into
Conversation
Generates a per-chart support-window matrix (N..N-3) in the README and a machine-readable docs/compatibility.json, derived from Chart.yaml version (authoritative N), git tags (history + release dates) and the optional lerian.studio/compatibility annotation (requires ranges). - N comes from Chart.yaml; N-1..N-3 from git tags (pre-releases segregated, tags above N discarded) - README table enriched in-place (Support, Released, per-dependency Requer columns), idempotent via BEGIN/END COMPAT markers, respects irregular layouts - app-version extraction shared with update-chart-version-readme via tableutil - single-service charts are not prompted for cross-compat (chart-type gate) - adds Masterminds/semver/v3 v3.2.1 (Go 1.21 floor) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- release.yml: build generate-compatibility, fetch tags, run it in the semantic-release prepareCmd (replacing update-chart-version-readme), and add docs/compatibility.json to the git assets so README + JSON ship in the single release commit (no second commit, no CI loop) - helm-chart-standard.yml: non-blocking --check drift step on PRs Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
First chart onboarded to the compatibility matrix. tracer is single-service (standalone), so the table shows the support window (N/N-1/N-2) with release dates; no cross-compat columns. docs/compatibility.json covers all 21 charts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Full Ring pre-dev output (research, prd, feature-map, trd, api-design, data-model, dependency-map, tasks, subtasks) plus BACKLOG (v2 items: agent/E2E requires filling, WARN visibility, EOL dates) and a minimal PROJECT_RULES.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a Go CLI that derives Helm support cycles and cross-chart compatibility from chart metadata and Git tags, renders ChangesCompatibility matrix generator
✨ Finishing Touches✨ Simplify code
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 19
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/scripts/generate-compatibility/annotation.go:
- Around line 41-49: Update parseCompatAnnotation to decode through a
yaml.Decoder configured with KnownFields(true) instead of yaml.Unmarshal, so
unknown or misspelled CompatAnnotation fields return an error while valid
annotations retain their current behavior.
In @.github/scripts/generate-compatibility/json_test.go:
- Around line 82-85: Stop discarding operation errors in the affected tests: in
.github/scripts/generate-compatibility/json_test.go lines 82-85, check and fail
on the error returned by renderJSON before inspecting its output; in
.github/scripts/generate-compatibility/write_readme_test.go lines 120-135, check
every fixture I/O error and the writeReadme error before comparing bytes, while
preserving the existing idempotency assertion.
In @.github/scripts/generate-compatibility/main.go:
- Around line 60-74: Update runWrite to validate a non-empty chart selector
against doc.Products before calling renderJSON or os.WriteFile; reject unknown
values by reporting an error to stderr and returning a nonzero status, while
preserving the existing write flow for valid or omitted chart values.
In @.github/scripts/generate-compatibility/markers_test.go:
- Around line 81-87: Update replaceCompatBlock to count COMPAT BEGIN and END
markers for the requested key, and return an error unless exactly one of each is
present. Preserve the existing malformed-marker error behavior while preventing
duplicate markers from being accepted or leaving orphaned blocks.
In @.github/scripts/generate-compatibility/markers.go:
- Around line 22-36: Update the marker scan in the compatibility-generation
function to reject duplicate BEGIN or END markers instead of overwriting their
indexes. Track whether each marker has already been seen, and return the
existing malformed-marker error path when either marker repeats; preserve the
current handling for missing or incorrectly ordered markers.
In @.github/scripts/generate-compatibility/window.go:
- Around line 102-104: Update the warning condition near segregateStable/byMinor
to detect when no stable tags remain, not only when tagVersions is empty. Emit
the INFO warning for both zero tags and all-pre-release tags, using message text
that accurately describes the absence of published stable tags.
In @.github/workflows/helm-chart-standard.yml:
- Around line 45-47: Remove the `|| true` suppression from the “Check
compatibility matrix drift (non-blocking)” workflow step, while retaining the
`--check` flag so drift remains non-blocking and compilation, module, and
filesystem failures correctly fail validation.
In `@docs/pre-dev/helm-version-compatibility-matrix/api-design.md`:
- Around line 23-25: Update the v1 annotation contract around compatibility,
including the V6 and “typical v1” examples/tests, so testedWith is accepted for
forward compatibility but optional and not populated by v1. Remove wording or
assertions that require or populate testedWith in v1, while preserving requires
behavior and the existing forward-compatible parsing contract.
In `@docs/pre-dev/helm-version-compatibility-matrix/prd.md`:
- Line 124: Align the documented scope with the tracer-only pilot: in
docs/pre-dev/helm-version-compatibility-matrix/prd.md lines 124-124, remove or
qualify the all-products automatic backfill requirement; in feature-map.md lines
33-33, remove F-8 or redefine it as annotation-provided data; in data-model.md
lines 126-126, state that testedWith is emitted only when declared; and in
research.md lines 118-118, update the recorded decision to reflect the selected
pilot scope.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-1-add-semver-dependency.md`:
- Around line 11-75: Make all copyable commands repository-portable by replacing
the hard-coded /home/gauchito/lerian/helm prefix with repository-relative paths.
Update every create, test, verification, and rollback command in
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-1-add-semver-dependency.md
(lines 11-75), ST-1-2-chart-directories-helper-tdd.md (lines 10-175), and
ST-1-3-read-chart-version-tdd.md (lines 10-159) to use paths such as
.github/scripts while preserving the documented commands and expected behavior.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-4-main-emit-current-json.md`:
- Line 10: Replace the contributor-specific /home/gauchito/lerian/helm prefix in
the executable commands at
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-4-main-emit-current-json.md:10,
T-2/ST-2-1-parse-annotation-twostep-tdd.md:10,
T-2/ST-2-2-validate-annotation-warnings-tdd.md:10,
T-2/ST-2-3-wire-annotation-into-state-and-doc.md:10,
T-3/ST-3-1-list-git-tags-for-dir-tdd.md:10,
T-3/ST-3-2-segregate-prereleases-and-group-by-minor-tdd.md:10,
T-3/ST-3-3-resolve-window-N-authoritative-tdd.md:14,
T-3/ST-3-4-wire-window-into-buildDoc-golden-tdd.md:10, and
T-3/ST-3-5-verify-window-against-real-repo.md:10. Use repository-relative
commands after changing to the repository root, or introduce a portable
$REPO_ROOT setup step.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-2-validate-annotation-warnings-tdd.md`:
- Around line 173-180: Update the import block in the documented Go snippet to
include the fmt package alongside strings, semver, and yaml so the fmt.Sprintf
usage compiles.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-3-resolve-window-N-authoritative-tdd.md`:
- Around line 231-245: The authoritative N cycle must not be replaced by a
higher historical patch version. In the logic building byMinor, assign nVer to
byMinor[nKey] unconditionally instead of retaining the greater existing version,
and add a regression case covering chartVersion 8.6.0 with an 8.6.1 tag to
ensure cycle 8.6 remains at 8.6.0 after filtering.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-5-verify-window-against-real-repo.md`:
- Around line 26-30: Update the verification command in “Passo 1” to use an
output path relative to the repository root, matching generate-compatibility’s
path resolution; adjust the subsequent references to read that same generated
file location instead of /tmp.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-1-assert-no-tier-and-schema-shape-tdd.md`:
- Around line 9-11: Make the commands in all seven listed subtasks
repository-portable by resolving the repository root with git rev-parse
--show-toplevel and deriving every script, artifact, and rollback path from that
root. Apply the replacement in ST-4-1, ST-4-2, ST-5-1, ST-5-2, ST-5-3, ST-5-4,
and ST-5-5 at their specified ranges; remove the hard-coded
/home/gauchito/lerian/helm path while preserving each command’s existing
behavior.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-7/ST-7-1-backfill-testedwith-annotations.md`:
- Around line 54-59: Update the validation command in Passo 4 to use a
repository-relative --output path, such as docs/compat-backfill.json, instead of
/tmp/compat-backfill.json. Keep the generator invocation and warning checks
unchanged.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-2-writeback-step-2B-skip-ci-actor-guard.md`:
- Around line 40-58: Reorder the workflow steps around the compatibility
generator so `git pull --rebase origin "${{ github.ref_name }}"` runs before
`./.github/scripts/generate-compatibility-bin`. Keep the subsequent diff check,
staging of `README.md` and `docs/compatibility.json`, commit, and push flow
unchanged, allowing the generator to run on a clean rebased worktree.
In `@docs/pre-dev/helm-version-compatibility-matrix/trd.md`:
- Around line 102-116: Update
docs/pre-dev/helm-version-compatibility-matrix/trd.md lines 102-116 to document
the implemented single-commit flow, removing the dedicated post-release 2B step,
separate write-back commit, and pull/rebase requirements. Update
docs/pre-dev/helm-version-compatibility-matrix/tasks.md lines 99-109 so T-8’s
deliverable, scope, and success criteria state that semantic-release generates
and includes the assets in the single release commit; no other sites require
changes.
- Line 13: Update the project_rules metadata in the Helm compatibility matrix to
state that docs/PROJECT_RULES.md exists, removing the claim that it is absent
and any guidance based on that claim.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: cb5aed4a-d8e6-4d33-881b-59b4a75365dd
⛔ Files ignored due to path filters (1)
.github/scripts/go.sumis excluded by!**/*.sum
📒 Files selected for processing (79)
.github/scripts/generate-compatibility/annotation.go.github/scripts/generate-compatibility/annotation_test.go.github/scripts/generate-compatibility/builddoc_test.go.github/scripts/generate-compatibility/chart.go.github/scripts/generate-compatibility/chart_test.go.github/scripts/generate-compatibility/check_test.go.github/scripts/generate-compatibility/ensure_test.go.github/scripts/generate-compatibility/json.go.github/scripts/generate-compatibility/json_test.go.github/scripts/generate-compatibility/main.go.github/scripts/generate-compatibility/markers.go.github/scripts/generate-compatibility/markers_test.go.github/scripts/generate-compatibility/render_readme.go.github/scripts/generate-compatibility/render_readme_test.go.github/scripts/generate-compatibility/resolve_test.go.github/scripts/generate-compatibility/run_test.go.github/scripts/generate-compatibility/section_test.go.github/scripts/generate-compatibility/state.go.github/scripts/generate-compatibility/state_test.go.github/scripts/generate-compatibility/tags.go.github/scripts/generate-compatibility/tags_test.go.github/scripts/generate-compatibility/testdata/golden_two_products.json.github/scripts/generate-compatibility/testdata/readme_irregular_golden.md.github/scripts/generate-compatibility/testdata/readme_irregular_in.md.github/scripts/generate-compatibility/warn.go.github/scripts/generate-compatibility/warn_test.go.github/scripts/generate-compatibility/window.go.github/scripts/generate-compatibility/window_test.go.github/scripts/generate-compatibility/write_readme.go.github/scripts/generate-compatibility/write_readme_test.go.github/scripts/go.mod.github/scripts/tableutil/appversions.go.github/scripts/tableutil/appversions_test.go.github/scripts/update-chart-version-readme/main.go.github/workflows/helm-chart-standard.yml.github/workflows/release.ymlREADME.mddocs/PROJECT_RULES.mddocs/compatibility.jsondocs/pre-dev/helm-version-compatibility-matrix/BACKLOG.mddocs/pre-dev/helm-version-compatibility-matrix/api-design.mddocs/pre-dev/helm-version-compatibility-matrix/data-model.mddocs/pre-dev/helm-version-compatibility-matrix/dependency-map.mddocs/pre-dev/helm-version-compatibility-matrix/feature-map.mddocs/pre-dev/helm-version-compatibility-matrix/prd.mddocs/pre-dev/helm-version-compatibility-matrix/research.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/README.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-1-add-semver-dependency.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-2-chart-directories-helper-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-3-read-chart-version-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-4-main-emit-current-json.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-1-parse-annotation-twostep-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-2-validate-annotation-warnings-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-3-wire-annotation-into-state-and-doc.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-1-list-git-tags-for-dir-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-2-segregate-prereleases-and-group-by-minor-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-3-resolve-window-N-authoritative-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-4-wire-window-into-buildDoc-golden-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-5-verify-window-against-real-repo.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-1-assert-no-tier-and-schema-shape-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-2-write-output-flag-and-commit-json.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-1-render-compat-table-lines-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-2-marker-block-replace-idempotent-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-3-locate-section-via-tableutil-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-4-ensure-block-create-section-adr5-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-5-wire-readme-write-into-main-golden-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-6-dry-run-disposable-clone-diff-review.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-2-check-mode-drift-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-7/ST-7-1-backfill-testedwith-annotations.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-1-build-binary-and-fetch-tags.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-2-writeback-step-2B-skip-ci-actor-guard.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-3-check-warning-in-standard-workflow.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-4-pr-title-scope-allowlist.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-5-validate-writeback-no-real-push.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-6-verify-no-ci-loop-on-bot-push.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-9/ST-9-1-document-annotation-contract.mddocs/pre-dev/helm-version-compatibility-matrix/tasks.mddocs/pre-dev/helm-version-compatibility-matrix/trd.md
- resolveWindow: keep the authoritative N cycle even when a higher patch tag exists (e.g. tag 8.6.1 while Chart.yaml N=8.6.0) — N no longer disappears - parse annotation with KnownFields(true) so misspelled keys fail instead of being silently dropped - reject unknown --chart before writing (exit 2, nothing written) - reject duplicate COMPAT markers instead of leaving an orphaned block - emit INFO for the 'tags exist but all pre-release' degraded case - --check step no longer masks operational errors (removed || true) - tests no longer discard renderJSON/writeReadme errors Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- api-design/prd: testedWith removed from v1 (returns in v2 via E2E), no backfill - trd/ADR-1b: write-back is single-commit 2A (semantic-release assets), not the dedicated-step 2B; ST-8-2 marked superseded - ST-3-3: unconditional N cycle (matches the resolveWindow fix) - trd: PROJECT_RULES.md now present; ST-2-2 adds missing fmt import - subtasks: repo-relative paths (git rev-parse) instead of a hardcoded checkout; --output uses repo-relative paths (it is resolved relative to --root) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
Endereçados todos os 19 comentários do review 🤖Obrigado pelo review detalhado — os 19 findings procediam. Resumo do que mudou (commits Correções de código (com testes de regressão):
Docs de planejamento (alinhados às decisões que evoluíram):
Idempotência preservada (validada 3× em clone limpo). |
guimoreirar
approved these changes
Jul 27, 2026
Contributor
|
@coderabbitai review |
✅ Action performedReview finished.
|
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (18)
.github/scripts/generate-compatibility/main.go (1)
114-118: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick winDo not treat every JSON read failure as drift.
This branch converts permission, I/O, and invalid-path errors into a warning and exit code
0, so the workflow can pass despite an operational failure. Treat only a missing file as non-blocking drift; return1for other read errors.Proposed fix
- actualJSON, err := os.ReadFile(filepath.Join(root, output)) - if err != nil || string(actualJSON) != string(expectedJSON) { + actualJSON, err := os.ReadFile(filepath.Join(root, output)) + if err != nil { + if !errors.Is(err, fs.ErrNotExist) { + fmt.Fprintf(stderr, "ERROR read %s: %v\n", output, err) + return 1 + } fmt.Fprintf(stderr, "WARN %s: compatibility JSON is stale\n", output) drift = true + } else if string(actualJSON) != string(expectedJSON) { + fmt.Fprintf(stderr, "WARN %s: compatibility JSON is stale\n", output) + drift = true }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/scripts/generate-compatibility/main.go around lines 114 - 118, Update the compatibility JSON read handling around os.ReadFile so only an os.IsNotExist error is treated as stale-file drift. For other read errors, report the operational failure and return exit code 1 instead of setting drift and continuing; preserve the existing content-comparison behavior for successfully read files.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-7/ST-7-1-backfill-testedwith-annotations.md (1)
1-75: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winMark ST-7-1 as superseded and non-executable.
This task still instructs agents to backfill
testedWithacross charts, contradicting the final v1 scope. Replace the actionable procedure with a historical/superseded note and remove the agent-execution marker, or explicitly defer it to v2.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-7/ST-7-1-backfill-testedwith-annotations.md` around lines 1 - 75, Replace the executable ST-7-1 procedure with a concise historical/superseded note stating that backfilling testedWith is outside the final v1 scope and is deferred to v2. Remove the “For Agents” execution marker and all actionable prerequisites, steps, commands, and verification instructions from this document.docs/pre-dev/helm-version-compatibility-matrix/api-design.md (2)
98-139: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAlign the CLI output contract with the implementation.
The documented per-chart write summary and
WARN <chart>...format do not matchmain.go, which emits an aggregate write message and warnings such asWARN README.md: ...orWARN docs/compatibility.json: .... Either update the contract to the implemented messages or change the CLI before treating these formats as stable.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/api-design.md` around lines 98 - 139, Align the documented CLI output contract with the behavior in main.go: update the write success summary and warning examples to match the actual aggregate message and emitted targets such as README.md and docs/compatibility.json, or modify the CLI implementation accordingly. Ensure the chosen contract consistently reflects stdout/stderr placement and the stable WARN prefix before finalizing it.
122-129: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winKeep usage and operational failures distinct.
docs/pre-dev/helm-version-compatibility-matrix/api-design.md#L122-L129: classify invalid/malformed flags as exit 2; reserve exit 1 for operational failures.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.md#L89-L117: replace “environment/usage error” with “environment/operational error.”🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/api-design.md` around lines 122 - 129, Keep usage and operational failures distinct: in docs/pre-dev/helm-version-compatibility-matrix/api-design.md lines 122-129, classify invalid or malformed flags as exit 2 and reserve exit 1 for operational failures; in docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.md lines 89-117, replace “environment/usage error” with “environment/operational error.”docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-5-wire-readme-write-into-main-golden-tdd.md (1)
57-207: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAlign both TDD documents with the final README-write orchestration.
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-5-wire-readme-write-into-main-golden-tdd.md#L57-L207: use the stderr-awarewriteReadmesignature and route the call throughrunWrite, not directmain()mutation.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.md#L137-L157: pass the diagnostic writer through the documentedrunWritecall.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-5-wire-readme-write-into-main-golden-tdd.md` around lines 57 - 207, Align the documented orchestration with the stderr-aware runWrite flow: in docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-5-wire-readme-write-into-main-golden-tdd.md (lines 57-207), update writeReadme and its tests to accept the diagnostic writer, and invoke it through runWrite rather than mutating main directly. In docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.md (lines 137-157), pass the diagnostic writer through the documented runWrite call.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-2-validate-annotation-warnings-tdd.md (1)
148-158: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winAdd a deterministic tie-breaker when sorting warnings.
The comparator returns equality for warnings with the same chart and rule. Since the inputs can originate from map iteration, multiple same-rule warnings can change order between runs and make stderr output nondeterministic. Sort by
Detail(or another stable key) after chart and rule.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-2-validate-annotation-warnings-tdd.md` around lines 148 - 158, Update the comparator in emitWarnings to use a deterministic tertiary key when Chart and Rule are equal. Compare warnings by Detail after chart and rule, preserving the existing ordering while ensuring same-rule warnings produce stable stderr output.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-3-check-warning-in-standard-workflow.md (1)
35-43: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick winDo not mask operational generator failures.
continue-on-error: truemakes the PR step ignore every nonzero exit, not just expected drift. Keep drift non-blocking, but allow operational errors fromgo runto fail the check (or explicitly distinguish drift from execution failures); otherwise broken release tooling can remain invisible.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-3-check-warning-in-standard-workflow.md` around lines 35 - 43, Update the “Compatibility matrix drift check (warning)” workflow step so expected drift remains non-blocking while operational failures from `go run ./generate-compatibility --check --root ../..` produce a nonzero result and fail the check. Remove the blanket `continue-on-error: true` and rely on the generator’s distinct exit behavior, or explicitly handle only the documented drift status without suppressing execution errors.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-3-wire-annotation-into-state-and-doc.md (1)
103-123: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winAvoid emitting V6 for malformed annotations.
A V1 parse failure returns
Compatas nil, then the second pass callsvalidateCompatand emits V6 (“no compatibility declared”). The chart actually has an invalid declaration, not an absent one, so preserve an invalid-state flag or suppress V6 for states that producedbadAnnotationError.Also applies to: 186-194
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-3-wire-annotation-into-state-and-doc.md` around lines 103 - 123, Update readChartState and the second-pass validation flow so charts whose parseCompatAnnotation result produces badAnnotationError are treated as invalid declarations, not as missing compatibility. Preserve the error state through to buildDoc and suppress the V6 “no compatibility declared” diagnostic for those states, while retaining V6 for genuinely absent annotations.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-5-validate-writeback-no-real-push.md (2)
41-68: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winMake the simulated release create real generator drift.
Appending a YAML comment does not change the chart version or generated artifacts, so Step 4 will commonly reach
NO_DRIFT. Step 4b then deletes and regenerates the same tracked JSON, which still leaves no diff and causesgit committo fail with “nothing to commit.” Change a version/input or intentionally modify a generated asset, then assert the resulting commit.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-5-validate-writeback-no-real-push.md` around lines 41 - 68, Atualize o Passo 3 para alterar uma versão ou outro input que realmente mude os artefatos gerados, em vez de apenas adicionar um comentário ao Chart.yaml; ajuste o fluxo para executar o gerador e confirmar a existência de drift antes do commit do writeback. Remova a dependência do Passo 4b como solução para NO_DRIFT e preserve a asserção de que o commit do writeback foi criado após o commit de release.
5-6: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winUpdate this procedure for the final single-commit release design.
The PR/TRD now use semantic-release
prepareCmdplus@semantic-release/gitassets, but this document still validates a separate post-release write-back commit,git pull --rebase, and a two-commit history. That tests a superseded flow and should be rewritten to validate generated assets included in the one semantic-release commit.Also applies to: 50-60
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-5-validate-writeback-no-real-push.md` around lines 5 - 6, Rewrite the procedure around the final single-commit semantic-release flow: validate that prepareCmd-generated assets are included in the commit created by `@semantic-release/git`, rather than testing a separate write-back commit, git pull --rebase, or a two-commit history. Preserve the disposable local clone and bare remote safety checks, and verify the resulting single commit is signed/GPG-verified when a key exists, supports git push --dry-run, and contains [skip ci].docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-1-parse-annotation-twostep-tdd.md (1)
118-129: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winAlign all annotation documents on strict unknown-field handling. The parser instructions do not reject unknown YAML keys, ST-2-2 incorrectly treats typed unmarshalling as V2 validation, and ST-9-1 says unknown keys are ignored; this contradicts the PR objective that unknown annotation fields are rejected.
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-1-parse-annotation-twostep-tdd.md#L118-L129: specify and implement explicit unknown-key detection.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-2-validate-annotation-warnings-tdd.md#L186-L189: document the actual V2 diagnostic path rather than relying on typed unmarshalling.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-9/ST-9-1-document-annotation-contract.md#L49-L53: replace “ignored with warning” with the final rejection/continuation contract.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-1-parse-annotation-twostep-tdd.md` around lines 118 - 129, Align the annotation contract across all three sites: in docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-1-parse-annotation-twostep-tdd.md lines 118-129, update parseCompatAnnotation to explicitly detect and reject unknown YAML keys; in docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-2-validate-annotation-warnings-tdd.md lines 186-189, document the actual V2 diagnostic path instead of treating typed unmarshalling as validation; and in docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-9/ST-9-1-document-annotation-contract.md lines 49-53, replace the ignored-with-warning behavior with rejection followed by continuation.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-1-render-compat-table-lines-tdd.md (1)
45-45: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winUpdate this subtask to the current renderer signature.
The current renderer takes
renderCompatTable(p Product, appLabels []string, appVersions map[string]string), while this guide calls and implements a one-argument function. Following it will not compile and will omit the app-version columns. Update the tests and implementation instructions to match the current API.Also applies to: 130-135
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-1-render-compat-table-lines-tdd.md` at line 45, Update the subtask’s renderCompatTable guidance and tests to use the current three-argument signature, passing Product, appLabels, and appVersions. Adjust the expected rendered output and implementation instructions so app-version columns are included, while preserving the existing joined output behavior.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-1-assert-no-tier-and-schema-shape-tdd.md (1)
53-64: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winPropagate
renderJSONerrors in the contract test.Ignoring the serialization error with
out, _ := renderJSON(doc)can turn a rendering failure into a misleading assertion failure or false pass. Fail the test with the returned error, consistent with the PR’s stated test-error propagation policy.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-1-assert-no-tier-and-schema-shape-tdd.md` around lines 53 - 64, Update TestRenderJSON_OmitsEmptyRequiresTestedWith to capture and check the error returned by renderJSON instead of discarding it. Fail the test immediately with the rendering error, then retain the existing JSON omission assertions for successful renders.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-2-segregate-prereleases-and-group-by-minor-tdd.md (1)
126-130: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winMake the order-independence test use different input orders.
revis initialized in descending order, thensort.Reversemakes it ascending—the same order asforward. Remove that sort or sort in the opposite direction; otherwise this regression test cannot detect order-dependent grouping.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-2-segregate-prereleases-and-group-by-minor-tdd.md` around lines 126 - 130, Update the order-independence test setup around forward, rev, and groupByMinor so rev remains in an order different from forward. Remove the sort.Sort(sort.Reverse(...)) call or change it to preserve descending order, ensuring the regression test exercises grouping with distinct input orders.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-2-marker-block-replace-idempotent-tdd.md (1)
144-158: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winReject duplicate compatibility markers.
This scan silently keeps the last BEGIN/END marker it sees. Duplicate markers can therefore replace the wrong block or leave extra markers in the README. Count each marker and return a malformed-document error when either marker appears more than once; add a regression test for duplicates.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-2-marker-block-replace-idempotent-tdd.md` around lines 144 - 158, Update the marker scan to count BEGIN and END occurrences instead of overwriting their indexes; return the existing malformed-document error when either count exceeds one, while preserving the missing, reversed, and no-marker behavior. Add a regression test covering duplicate compatibility markers and verifying the document is rejected without replacing a block.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-5-verify-window-against-real-repo.md (1)
21-29: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winRun this verification in a disposable location.
--output docs/compat-verify.jsonis relative to--root, so these commands write generated files into the repository. The latergit statuscheck also excludesdocs/compat-verify*.json. Use a disposable clone/temp root, or update the generator to support an output path outside--root, and include all generated artifacts in cleanup/status checks.Also applies to: 44-57
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-5-verify-window-against-real-repo.md` around lines 21 - 29, Update the verification steps to run against a disposable clone or temporary repository root rather than the working repository, ensuring the relative --output path cannot create files in the checkout. Include every generated artifact in cleanup and git status validation, and remove the existing exclusion of compat-verify files; preserve the verification commands’ intended behavior.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-4-wire-window-into-buildDoc-golden-tdd.md (1)
110-142: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winPreserve the caller-provided diagnostics writer in
buildDoc.The current CLI passes
stderrintobuildDoc, but this plan changes the function to two arguments and writes directly toos.Stderr. That bypasses the caller’s writer and prevents tests from reliably capturing warnings. Keep anio.Writerparameter, use it for all diagnostics, and pass a buffer orio.Discardfrom the golden test.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-4-wire-window-into-buildDoc-golden-tdd.md` around lines 110 - 142, Preserve the caller-provided diagnostics writer in buildDoc by retaining an io.Writer parameter alongside root and lister, and route all emitWarnings and tag-listing failure output through it instead of os.Stderr. Update main and the golden test caller to pass stderr, a buffer, or io.Discard as appropriate while keeping the gitTagLister wiring unchanged.docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-3-resolve-window-N-authoritative-tdd.md (1)
215-216: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winCover the all-pre-release tag case explicitly.
The documented INFO condition only checks
len(tagVersions) == 0. A non-empty list containing only prereleases is a distinct degraded state and should also emit INFO while producing only the authoritative N cycle. Add this case to the contract and regression tests.Also applies to: 258-260
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-3-resolve-window-N-authoritative-tdd.md` around lines 215 - 216, Update the FR-7 contract and regression tests for the all-pre-release tag case: when tagVersions is non-empty but contains no stable releases, emit the documented INFO message and produce only the authoritative N cycle. Keep the existing zero-tag and fewer-than-four-minors behaviors unchanged, and cover the new condition explicitly in both referenced test areas.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/scripts/generate-compatibility/run_test.go:
- Around line 59-73: Update the “unknown --chart => exit 2, nothing written”
test around run to capture README.md contents before invoking run, then read and
compare it afterward. Assert that README.md remains unchanged alongside the
existing compatibility.json absence check, preserving the test’s
no-partial-write guarantee.
In @.github/scripts/generate-compatibility/window.go:
- Around line 107-116: Update the degraded-window check in the compatibility
window resolution flow to use the count of stable cycles remaining after the ≤N
filtering, rather than stableCyclesFromTags counted from byMinor before
filtering. When no cycles survive, preserve the no-published-tags message for
empty tagVersions, retain the only-pre-release message where applicable, and add
an accurate diagnostic for existing stable tags that were all above N.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-1-assert-no-tier-and-schema-shape-tdd.md`:
- Line 85: Align alternate-output verification with the generator’s
--root-relative --output semantics: in
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-1-assert-no-tier-and-schema-shape-tdd.md:85,
replace /tmp/compat-t4.json with the actual resolved repository-relative output
path and inspect that file; in
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-2-write-output-flag-and-commit-json.md:34,
use the same resolved path for both generation and existence checks.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-2-writeback-step-2B-skip-ci-actor-guard.md`:
- Around line 3-8: Make this superseded 2B task non-executable by removing the
“For Agents” execution marker and the detailed implementation procedure. Replace
the content with a brief historical note stating that 2B was not implemented,
the design reverted to 2A via semantic-release, and reference the updated ADR-1b
and TRD §5.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-4-pr-title-scope-allowlist.md`:
- Around line 25-29: Replace the broad text and fixed-line verification
procedures with structure-aware YAML parsing. In
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-4-pr-title-scope-allowlist.md
lines 25-29, inspect the actual scopes allowlist node; in lines 49-53, derive
and verify scopes from that parsed node. In
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-6-verify-no-ci-loop-on-bot-push.md
lines 19-23, validate push.paths-ignore structurally; in lines 51-59, validate
job and step guard placement against their parsed YAML nodes.
---
Outside diff comments:
In @.github/scripts/generate-compatibility/main.go:
- Around line 114-118: Update the compatibility JSON read handling around
os.ReadFile so only an os.IsNotExist error is treated as stale-file drift. For
other read errors, report the operational failure and return exit code 1 instead
of setting drift and continuing; preserve the existing content-comparison
behavior for successfully read files.
In `@docs/pre-dev/helm-version-compatibility-matrix/api-design.md`:
- Around line 98-139: Align the documented CLI output contract with the behavior
in main.go: update the write success summary and warning examples to match the
actual aggregate message and emitted targets such as README.md and
docs/compatibility.json, or modify the CLI implementation accordingly. Ensure
the chosen contract consistently reflects stdout/stderr placement and the stable
WARN prefix before finalizing it.
- Around line 122-129: Keep usage and operational failures distinct: in
docs/pre-dev/helm-version-compatibility-matrix/api-design.md lines 122-129,
classify invalid or malformed flags as exit 2 and reserve exit 1 for operational
failures; in
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.md
lines 89-117, replace “environment/usage error” with “environment/operational
error.”
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-1-parse-annotation-twostep-tdd.md`:
- Around line 118-129: Align the annotation contract across all three sites: in
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-1-parse-annotation-twostep-tdd.md
lines 118-129, update parseCompatAnnotation to explicitly detect and reject
unknown YAML keys; in
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-2-validate-annotation-warnings-tdd.md
lines 186-189, document the actual V2 diagnostic path instead of treating typed
unmarshalling as validation; and in
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-9/ST-9-1-document-annotation-contract.md
lines 49-53, replace the ignored-with-warning behavior with rejection followed
by continuation.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-2-validate-annotation-warnings-tdd.md`:
- Around line 148-158: Update the comparator in emitWarnings to use a
deterministic tertiary key when Chart and Rule are equal. Compare warnings by
Detail after chart and rule, preserving the existing ordering while ensuring
same-rule warnings produce stable stderr output.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-3-wire-annotation-into-state-and-doc.md`:
- Around line 103-123: Update readChartState and the second-pass validation flow
so charts whose parseCompatAnnotation result produces badAnnotationError are
treated as invalid declarations, not as missing compatibility. Preserve the
error state through to buildDoc and suppress the V6 “no compatibility declared”
diagnostic for those states, while retaining V6 for genuinely absent
annotations.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-2-segregate-prereleases-and-group-by-minor-tdd.md`:
- Around line 126-130: Update the order-independence test setup around forward,
rev, and groupByMinor so rev remains in an order different from forward. Remove
the sort.Sort(sort.Reverse(...)) call or change it to preserve descending order,
ensuring the regression test exercises grouping with distinct input orders.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-3-resolve-window-N-authoritative-tdd.md`:
- Around line 215-216: Update the FR-7 contract and regression tests for the
all-pre-release tag case: when tagVersions is non-empty but contains no stable
releases, emit the documented INFO message and produce only the authoritative N
cycle. Keep the existing zero-tag and fewer-than-four-minors behaviors
unchanged, and cover the new condition explicitly in both referenced test areas.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-4-wire-window-into-buildDoc-golden-tdd.md`:
- Around line 110-142: Preserve the caller-provided diagnostics writer in
buildDoc by retaining an io.Writer parameter alongside root and lister, and
route all emitWarnings and tag-listing failure output through it instead of
os.Stderr. Update main and the golden test caller to pass stderr, a buffer, or
io.Discard as appropriate while keeping the gitTagLister wiring unchanged.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-5-verify-window-against-real-repo.md`:
- Around line 21-29: Update the verification steps to run against a disposable
clone or temporary repository root rather than the working repository, ensuring
the relative --output path cannot create files in the checkout. Include every
generated artifact in cleanup and git status validation, and remove the existing
exclusion of compat-verify files; preserve the verification commands’ intended
behavior.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-1-assert-no-tier-and-schema-shape-tdd.md`:
- Around line 53-64: Update TestRenderJSON_OmitsEmptyRequiresTestedWith to
capture and check the error returned by renderJSON instead of discarding it.
Fail the test immediately with the rendering error, then retain the existing
JSON omission assertions for successful renders.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-1-render-compat-table-lines-tdd.md`:
- Line 45: Update the subtask’s renderCompatTable guidance and tests to use the
current three-argument signature, passing Product, appLabels, and appVersions.
Adjust the expected rendered output and implementation instructions so
app-version columns are included, while preserving the existing joined output
behavior.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-2-marker-block-replace-idempotent-tdd.md`:
- Around line 144-158: Update the marker scan to count BEGIN and END occurrences
instead of overwriting their indexes; return the existing malformed-document
error when either count exceeds one, while preserving the missing, reversed, and
no-marker behavior. Add a regression test covering duplicate compatibility
markers and verifying the document is rejected without replacing a block.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-5-wire-readme-write-into-main-golden-tdd.md`:
- Around line 57-207: Align the documented orchestration with the stderr-aware
runWrite flow: in
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-5-wire-readme-write-into-main-golden-tdd.md
(lines 57-207), update writeReadme and its tests to accept the diagnostic
writer, and invoke it through runWrite rather than mutating main directly. In
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.md
(lines 137-157), pass the diagnostic writer through the documented runWrite
call.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-7/ST-7-1-backfill-testedwith-annotations.md`:
- Around line 1-75: Replace the executable ST-7-1 procedure with a concise
historical/superseded note stating that backfilling testedWith is outside the
final v1 scope and is deferred to v2. Remove the “For Agents” execution marker
and all actionable prerequisites, steps, commands, and verification instructions
from this document.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-3-check-warning-in-standard-workflow.md`:
- Around line 35-43: Update the “Compatibility matrix drift check (warning)”
workflow step so expected drift remains non-blocking while operational failures
from `go run ./generate-compatibility --check --root ../..` produce a nonzero
result and fail the check. Remove the blanket `continue-on-error: true` and rely
on the generator’s distinct exit behavior, or explicitly handle only the
documented drift status without suppressing execution errors.
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-5-validate-writeback-no-real-push.md`:
- Around line 41-68: Atualize o Passo 3 para alterar uma versão ou outro input
que realmente mude os artefatos gerados, em vez de apenas adicionar um
comentário ao Chart.yaml; ajuste o fluxo para executar o gerador e confirmar a
existência de drift antes do commit do writeback. Remova a dependência do Passo
4b como solução para NO_DRIFT e preserve a asserção de que o commit do writeback
foi criado após o commit de release.
- Around line 5-6: Rewrite the procedure around the final single-commit
semantic-release flow: validate that prepareCmd-generated assets are included in
the commit created by `@semantic-release/git`, rather than testing a separate
write-back commit, git pull --rebase, or a two-commit history. Preserve the
disposable local clone and bare remote safety checks, and verify the resulting
single commit is signed/GPG-verified when a key exists, supports git push
--dry-run, and contains [skip ci].
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 7818f9e7-205b-4d34-a066-b27f99c23550
📒 Files selected for processing (44)
.github/scripts/generate-compatibility/annotation.go.github/scripts/generate-compatibility/annotation_test.go.github/scripts/generate-compatibility/json_test.go.github/scripts/generate-compatibility/main.go.github/scripts/generate-compatibility/markers.go.github/scripts/generate-compatibility/markers_test.go.github/scripts/generate-compatibility/resolve_test.go.github/scripts/generate-compatibility/run_test.go.github/scripts/generate-compatibility/window.go.github/scripts/generate-compatibility/write_readme_test.go.github/workflows/helm-chart-standard.ymldocs/pre-dev/helm-version-compatibility-matrix/api-design.mddocs/pre-dev/helm-version-compatibility-matrix/prd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-1-add-semver-dependency.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-2-chart-directories-helper-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-3-read-chart-version-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-1/ST-1-4-main-emit-current-json.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-1-parse-annotation-twostep-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-2-validate-annotation-warnings-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-2/ST-2-3-wire-annotation-into-state-and-doc.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-1-list-git-tags-for-dir-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-2-segregate-prereleases-and-group-by-minor-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-3-resolve-window-N-authoritative-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-4-wire-window-into-buildDoc-golden-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-3/ST-3-5-verify-window-against-real-repo.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-1-assert-no-tier-and-schema-shape-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-2-write-output-flag-and-commit-json.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-1-render-compat-table-lines-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-2-marker-block-replace-idempotent-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-3-locate-section-via-tableutil-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-4-ensure-block-create-section-adr5-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-5-wire-readme-write-into-main-golden-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-6-dry-run-disposable-clone-diff-review.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-2-check-mode-drift-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-7/ST-7-1-backfill-testedwith-annotations.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-1-build-binary-and-fetch-tags.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-2-writeback-step-2B-skip-ci-actor-guard.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-3-check-warning-in-standard-workflow.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-4-pr-title-scope-allowlist.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-5-validate-writeback-no-real-push.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-6-verify-no-ci-loop-on-bot-push.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-9/ST-9-1-document-annotation-contract.mddocs/pre-dev/helm-version-compatibility-matrix/trd.md
The cross-compatibility column used the Portuguese 'Requer' while every other column (Chart Version, Released, Support) is English. Rename to 'Requires' for consistency. In-place regeneration migrates any legacy 'Requer' block to 'Requires' (single block, idempotent). Planning docs updated to match. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/pre-dev/helm-version-compatibility-matrix/trd.md`:
- Around line 91-95: Remove the testedWith field and its midaz-helm example from
the v1 annotation contract in the documented example. Keep the requires
relationship and its existing v1 guidance unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 4511eb7e-874e-4284-9d76-ec0763c39dae
📒 Files selected for processing (11)
.github/scripts/generate-compatibility/markers.go.github/scripts/generate-compatibility/markers_test.go.github/scripts/generate-compatibility/render_readme.go.github/scripts/generate-compatibility/render_readme_test.go.github/scripts/generate-compatibility/testdata/readme_irregular_golden.md.github/scripts/generate-compatibility/write_readme_test.godocs/pre-dev/helm-version-compatibility-matrix/api-design.mddocs/pre-dev/helm-version-compatibility-matrix/data-model.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-5/ST-5-1-render-compat-table-lines-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/tasks.mddocs/pre-dev/helm-version-compatibility-matrix/trd.md
- resolveWindow: INFO now fires when tags exist but none map below N (all pre-release OR all above N), counting cycles after the >N filter instead of raw byMinor; clearer 'no usable tags below N' message - run_test: assert README stays unchanged on unknown --chart (not just JSON) - api-design: invalid/malformed flags are exit 2 (usage), not exit 1 - ST-8-2: rewritten as non-executable (superseded 2B); removed For Agents marker - ST-4-1: --output uses repo-relative path (resolved against --root) - ST-6-1: exit-code terminology (operational vs usage) - ST-8-4: note structural (yq) verification alternative to text grep Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
2º review endereçado 🤖 (commit
|
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.md`:
- Around line 97-99: Update the exit-code documentation comment to classify an
unreadable --root as operational error 1, while reserving usage error 2 for
invalid or conflicting flags; keep the existing success and stdout/stderr
behavior descriptions unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 6a8eec6a-1d7d-4afd-a42b-09cbc9d4e289
📒 Files selected for processing (8)
.github/scripts/generate-compatibility/resolve_test.go.github/scripts/generate-compatibility/run_test.go.github/scripts/generate-compatibility/window.godocs/pre-dev/helm-version-compatibility-matrix/api-design.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-4/ST-4-1-assert-no-tier-and-schema-shape-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-2-writeback-step-2B-skip-ci-actor-guard.mddocs/pre-dev/helm-version-compatibility-matrix/subtasks/T-8/ST-8-4-pr-title-scope-allowlist.md
- trd.md: annotation example no longer shows testedWith as a v1 field - ST-6-1: exit-code comment corrects unreadable root as operational (exit 1), reserving exit 2 for invalid/conflicting flags and unknown --chart Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.md`:
- Around line 97-100: Update the documented TestRun_ExitCodes TDD recipe to
cover the stated exit-code contract: add an unknown --chart case asserting exit
code 2 and no files changed, plus an invalid-flag case also asserting the
usage-error code. Use the existing run_test.go unknown-chart behavior as the
reference while preserving the current success, warning, and operational-error
assertions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 5d414e0f-f9d4-4aeb-8e7f-565695a9ad6d
📒 Files selected for processing (2)
docs/pre-dev/helm-version-compatibility-matrix/subtasks/T-6/ST-6-1-flag-parsing-exit-codes-tdd.mddocs/pre-dev/helm-version-compatibility-matrix/trd.md
The Goal and TestRun_ExitCodes recipe now cover the unknown --chart => exit 2 (nothing written) case, matching the exit-code contract comment and the real run_test.go assertion. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.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
3 participants
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.
O que é
Automação da matriz de compatibilidade de versões dos Helm charts. Gera, por chart, uma tabela de suporte (janela N..N-3 seguindo o contrato LTS) no README + um
docs/compatibility.jsonlegível por máquina — tudo derivado automaticamente, sem manutenção manual.Piloto: apenas o chart
tracerfoi onboardado nesta entrega (single-service, valida o fluxo de ponta a ponta). Os demais charts seguem inalterados até serem migrados.Como fica no README
A ferramenta enriquece a tabela
#### Application Version Mappingque já existe (substitui in-place, entre marcadores<!-- BEGIN/END COMPAT -->), sem duplicar nem tocar a prosa ao redor.Antes (só a versão atual)
Depois (janela de suporte N..N-3 + datas)
2.1.02.0.01.0.0Exemplo com dependência declarada (potencial da coluna "Requires")
Quando um chart declara
requiresna annotationlerian.studio/compatibility, a tabela ganha uma coluna por dependência. Ex. de umplugin-feesque dependesse demidazeplugin-access-manager:7.2.07.1.0≤ 5.4.0Colunas
Chart.yaml.version(N autoritativo) + tags git (N-1..N-3). Vale para todos os charts, automático.creatordate).{componente}.image.tagnovalues.yaml(só a linha N; históricas ficam—).requires.Mudanças
.github/scripts/generate-compatibility/: nova ferramenta Go (espelhagenerate-values-schemas). AdicionaMasterminds/semver/v3 v3.2.1(piso Go 1.21).tableutil/appversions.go: extração de app-version por{componente}.image.tagcompartilhada comupdate-chart-version-readme(dedup).release.yml: noprepareCmddo semantic-release,generate-compatibilitysubstituiupdate-chart-version-readme; adicionagit fetch --tagse odocs/compatibility.jsonaos assets → commit único do release (sem 2º commit, sem loop de CI).helm-chart-standard.yml: step--checkde drift não-bloqueante no PR.docs/pre-dev/: planejamento Ring completo (research→subtasks) + BACKLOG (itens v2: preenchimento derequiresvia agent/E2E, visibilidade de WARN, datas de EOL).Validado
go testverde (generate-compatibility + tableutil); idempotente (2× = mesmo byte); substituição da tabela in-place sem duplicar.prepareCmdsimulado da raiz + commit dos assets em dry-run.app-syncsó fazyq -i .appVersion— a annotation de compatibilidade sobrevive (diff provou byte-idêntico).Ressalvas / atenção no merge
helm-chart-standard.yml --checké não-bloqueante.semantic-release(orquestração de plugins) só se confirma no primeiro release após o merge — vale acompanhar. Se oprepareCmdfalhar, o release aborta antes de commitar (erro visível e reversível, não corrompe nada).🤖 Generated with Claude Code