From a62f513862cae8f17ec819b84eaaf6f31f60a1c1 Mon Sep 17 00:00:00 2001 From: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 08:58:47 +0000 Subject: [PATCH 1/3] docs(#3503): document RPM lockfile scope for UBI bump PRs Add a UBI Base Image Updates section to AGENTS.md that explains the relationship between hack/ubi-base-image-bump.sh, hack/update-rpm-lock.sh, and the scope of rpms.lock.yaml. The section documents that rpms.lock.yaml is regenerated from rpms.in.yaml and only tracks the explicitly listed packages (ca-certificates, jq, gzip). RPMs that live inside the ubi-minimal base image are not tracked, so a digest bump that only ships updates to base-image-bundled RPMs produces no diff in the lockfile even when regeneration ran successfully. The absence of documentation for this behavior led to a false-positive review finding on PR #3499 that claimed the lockfile was not regenerated, costing ~1.5 hours of reviewer back-and-forth. The added section gives reviewers (human and automated) enough context to dismiss the same finding on future UBI bump PRs. Also carries the release-v* branch guidance so all UBI-bump review context lives in one place. Note: pre-commit hooks were not run. `pre-commit` could not fetch the conforma/hooks repository (HTTP 403 from the sandbox), and the only configured hook (check-commit-message) runs at the commit-msg stage, not against files. The 'resolves: #3503' trailer below is formatted to satisfy that hook when it runs in CI. resolves: #3503 --- AGENTS.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 650d3c033..37ca41bec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -112,6 +112,53 @@ Read these before modifying the corresponding areas: - [internal/validate/vsa/DESIGN.md](internal/validate/vsa/DESIGN.md) — VSA: storage backends, DSSE signing rationale, expiration model - [acceptance/README.md](acceptance/README.md) — acceptance test framework, Testcontainers, WireMock, snapshot testing +## UBI Base Image Updates + +The project pins the `ubi-minimal` base image digest in three Dockerfiles: + +- `Dockerfile` (production) +- `Dockerfile.dist` (distribution) +- `acceptance/kubernetes/kind/acceptance.Dockerfile` (acceptance tests) + +The script `hack/ubi-base-image-bump.sh` updates all three files to the same +digest and then invokes `hack/update-rpm-lock.sh` to regenerate `rpms.lock.yaml`. +Renovate raises the same bump automatically; the script exists for manual runs +between Renovate PRs. All three Dockerfiles must pin the same digest, and the +lockfile must be regenerated after any digest bump. + +### RPM lockfile scope + +`rpms.lock.yaml` is generated from `rpms.in.yaml` and only tracks the packages +explicitly listed there — currently `ca-certificates`, `jq`, and `gzip`. RPMs +that ship inside the base image itself (for example `curl-minimal`, `glib2`, +`libcurl-minimal`, `libnghttp2`) are **not** tracked in the lockfile. + +Consequence: when a UBI base image digest bump ships updates only to +base-image-bundled RPMs and the tracked packages' available versions do not +change, `hack/update-rpm-lock.sh` runs successfully but produces no diff in +`rpms.lock.yaml`. A commit that bumps the digest in the Dockerfiles without +touching `rpms.lock.yaml` is the expected outcome in that case, not evidence +that the lockfile was skipped. + +### Review guidance for UBI bump PRs + +On any PR that bumps the `ubi-minimal` digest: + +- Do **not** flag "`rpms.lock.yaml` was not regenerated" as a finding solely + because the lockfile is unchanged. Regeneration is a no-op when no tracked + package's version changed, and that is the common case. Confirm the lockfile + was regenerated only by asking the author (or checking CI logs) — the diff + alone cannot prove it either way. +- If the concern is that a new base-image-bundled RPM should be tracked + explicitly, that is a separate change to `rpms.in.yaml`, not a bug in the + bump PR. + +On `release-v*` branches, bump PRs may intentionally update only the production +Dockerfiles (`Dockerfile`, `Dockerfile.dist`) and skip the acceptance +Dockerfile, since acceptance test infrastructure is typically not backported. +The coordinated update set in `hack/ubi-base-image-bump.sh` applies to `main`; +a narrower scope on release branches is expected, not stale. + ## Claude Code Skills Skills live in `.claude/skills//SKILL.md`. They are **step-by-step executable workflows** From 957dc760688f29d64738a2578b19644af9f925a0 Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 24 Sep 2026 12:40:54 +0000 Subject: [PATCH 2/3] docs(#3503): clarify rpms.lock.yaml also tracks resolved dependencies Reviewer pointed out that rpms.lock.yaml carries not only the packages explicitly listed in rpms.in.yaml (ca-certificates, jq, gzip) but also their resolved transitive dependencies (e.g. oniguruma pulled in as a dependency of jq). Update the 'RPM lockfile scope' section in AGENTS.md to spell out both kinds of entries, define 'tracked packages' as the union of the two, and update the follow-on 'no diff' explanation so it covers transitive-dependency version changes as well. Note: pre-commit hooks were not run because the sandbox could not fetch the conforma/hooks repository (HTTP 403). The only configured hook is check-commit-message; no file-content hook applies to this docs change. Addresses #3575 --- AGENTS.md | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 37ca41bec..b85b8fad0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -128,17 +128,32 @@ lockfile must be regenerated after any digest bump. ### RPM lockfile scope -`rpms.lock.yaml` is generated from `rpms.in.yaml` and only tracks the packages -explicitly listed there — currently `ca-certificates`, `jq`, and `gzip`. RPMs -that ship inside the base image itself (for example `curl-minimal`, `glib2`, -`libcurl-minimal`, `libnghttp2`) are **not** tracked in the lockfile. +`rpms.lock.yaml` is generated from `rpms.in.yaml`. It contains two kinds of +entries, and both are "tracked" for the purposes of this section: + +1. The packages explicitly listed in `rpms.in.yaml` — currently + `ca-certificates`, `jq`, and `gzip`. +2. Their resolved transitive dependencies pulled in by the resolver + (for example `oniguruma`, which the lockfile carries as a dependency + of `jq`). These are not named in `rpms.in.yaml` but appear in + `rpms.lock.yaml` because the resolver had to pin them. + +Together, "tracked packages" below means the union of (1) and (2): every RPM +that ends up in `rpms.lock.yaml`, whether requested directly or pulled in +transitively. + +RPMs that ship inside the base image itself (for example `curl-minimal`, +`glib2`, `libcurl-minimal`, `libnghttp2`) are **not** tracked in the lockfile — +they are neither listed in `rpms.in.yaml` nor pulled in as a transitive +dependency of anything that is. Consequence: when a UBI base image digest bump ships updates only to -base-image-bundled RPMs and the tracked packages' available versions do not -change, `hack/update-rpm-lock.sh` runs successfully but produces no diff in -`rpms.lock.yaml`. A commit that bumps the digest in the Dockerfiles without -touching `rpms.lock.yaml` is the expected outcome in that case, not evidence -that the lockfile was skipped. +base-image-bundled RPMs and no tracked package's available version changed +(neither an explicitly listed package nor any of its resolved transitive +dependencies), `hack/update-rpm-lock.sh` runs successfully but produces no +diff in `rpms.lock.yaml`. A commit that bumps the digest in the Dockerfiles +without touching `rpms.lock.yaml` is the expected outcome in that case, not +evidence that the lockfile was skipped. ### Review guidance for UBI bump PRs From 0c7c9a661b4702a26936d687f1303a803a59df6f Mon Sep 17 00:00:00 2001 From: fullsend-fix <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Thu, 24 Sep 2026 12:57:46 +0000 Subject: [PATCH 3/3] docs(#3503): use title case for new AGENTS.md H3 headings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename "### RPM lockfile scope" to "### RPM Lockfile Scope" and "### Review guidance for UBI bump PRs" to "### Review Guidance for UBI Bump PRs" for consistency with the majority title-case pattern used by other multi-word H3 headings in AGENTS.md (e.g. "Acceptance Tests", "Test Tags", "Format"). Addresses two [naming-convention] findings from the review of PR #3575. The two [intent-coherence] and one [protected-path] findings are recorded as disagreements in the fix agent's structured output — they call for external coordination or human approval rather than a content change here. Note: pre-commit could not fetch its hook repositories (network blocked in sandbox); the sole configured hook (check-commit-message, commit-msg stage) has no file-scoped fallback. Tests and Go linters were not run because this change is heading text in AGENTS.md only, with no code paths affected. Addresses #3575 --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b85b8fad0..d6ffbe3ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,7 +126,7 @@ Renovate raises the same bump automatically; the script exists for manual runs between Renovate PRs. All three Dockerfiles must pin the same digest, and the lockfile must be regenerated after any digest bump. -### RPM lockfile scope +### RPM Lockfile Scope `rpms.lock.yaml` is generated from `rpms.in.yaml`. It contains two kinds of entries, and both are "tracked" for the purposes of this section: @@ -155,7 +155,7 @@ diff in `rpms.lock.yaml`. A commit that bumps the digest in the Dockerfiles without touching `rpms.lock.yaml` is the expected outcome in that case, not evidence that the lockfile was skipped. -### Review guidance for UBI bump PRs +### Review Guidance for UBI Bump PRs On any PR that bumps the `ubi-minimal` digest: