Skip to content

docs(readme): correct the versioning claim that Dependabot bumps consumers - #578

Merged
kyle-sexton merged 3 commits into
mainfrom
docs/versioning-readme-drift
Sep 8, 2026
Merged

docs(readme): correct the versioning claim that Dependabot bumps consumers#578
kyle-sexton merged 3 commits into
mainfrom
docs/versioning-readme-drift

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

No related issue: drift found while cutting the v0.24.0 release for PR #577; the correction is small enough to carry on its own PR rather than open an issue first.

Summary

The ## Versioning section justified the tag-per-change policy with a claim
that is not true of this repository's consumers:

cutting one after every meaningful change keeps main at the latest tag so
Dependabot's github-actions group bumps consumers to a tagged SHA instead
of tracking main HEAD by drift.

Nothing bumps consumers automatically. Consumers pin ci-workflows by full
40-character commit SHA with a # vX.Y.Z trailing comment, and that pin moves
only through a reviewed pull request in the consumer's own repository. At
least one consumer's Dependabot configuration explicitly ignores
melodic-software/ci-workflows/*, so the github-actions group never opens a
bump PR for this repository at all.

The claim mattered in practice: PR #577 added timeout-minutes to eight steps
in .github/workflows/checks.yml and merged at 2c1de45, but because
consumers pin by SHA and no release existed at that commit, the change reached
no consumer. Believing the README meant believing the change had already
propagated.

SECURITY.md stated the same two now-corrected claims, that consumers pick up
fixes via an advancing pinned SHA Dependabot bumps and that they should keep
the github-actions Dependabot ecosystem enabled, and is rewritten here to the
same reviewed-repin model.

Fix

Replaced the Dependabot clause with what actually happens, and left the rest of
the paragraph's reasoning intact:

  • The stated reason to cut a release is now that it makes a tagged SHA
    available to pin to, which is the true benefit.
  • Added one sentence stating the real propagation path: SHA pin plus version
    comment, moved by a reviewed PR in the consumer's repository.
  • The following release-gap-check sentence was already correct and is
    preserved verbatim; it is only rewrapped because the replacement changed the
    line boundaries.
  • SECURITY.md: the ## Supported versions paragraph now says a security fix
    reaches a consumer only when that consumer repins by reviewed pull request,
    names the release-gap-check advisory issue, and tells consumers to watch
    this repository's Releases; the Pin by full commit SHA bullet now says to
    keep this repository out of Dependabot's github-actions updates with an
    ignore entry and move the pin by reviewed pull request.

The diff is one README paragraph plus two SECURITY.md sentences.

Verification

  • npx markdownlint-cli2@0.23.2 README.md against the repo's own
    .markdownlint-cli2.jsonc:
    Summary: 0 issues in 0 files, exit 0.
  • npx markdownlint-cli2 --config .markdownlint-cli2.jsonc SECURITY.md:
    Summary: 0 issues in 0 files, exit 0.
  • git diff --stat for the README commits: README.md | 15 +++++++-------,
    1 file changed, 8 insertions(+), 7 deletions(-).
  • git diff --stat for the SECURITY.md commit: SECURITY.md | 14 +++++++-----,
    1 file changed, 9 insertions(+), 5 deletions(-).
  • git diff | grep '^+.*[ \t]$' returns no matches, so no trailing whitespace
    was introduced.
  • Read back the rendered paragraph to confirm the release-gap-check sentence
    survives word-for-word and only its line wrapping changed.
  • Confirmed the underlying facts before writing: release.yml computes the
    next version from published Releases and creates a tag plus Release at
    GITHUB_SHA; nothing in it or in this repository opens a bump PR against a
    consumer.

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_01L5ZJnwTRCgc31bmfrdugyU

…umers

The §Versioning paragraph justified cutting a release after every meaningful
change by claiming Dependabot's `github-actions` group then bumps consumers to
the tagged SHA. It does not. Consumers pin this repository by full commit SHA
with a `# vX.Y.Z` comment and move that pin through a reviewed pull request in
their own repository; at least one consumer's Dependabot config explicitly
ignores `melodic-software/ci-workflows/*`.

The reason to cut a release is unchanged — it makes a tagged SHA available to
pin to — and the `release-gap-check` advisory-issue sentence that follows was
already correct and is preserved verbatim, only rewrapped.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L5ZJnwTRCgc31bmfrdugyU
@kyle-sexton
kyle-sexton marked this pull request as ready for review September 8, 2026 16:21
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 8, 2026

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review Completed 2026-09-08T16:23:54.384700Z 9aa1da8 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@claude

claude Bot commented Sep 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 2m 9s —— View job


Claude finished the code-review lane for PR #578

  • Read trigger instructions and REVIEW.md scope (code-review lane; security lane exists in this repo via claude-security-review.yml, so security findings are out of scope here)
  • Fetched diff (git diff origin/main...HEAD -- README.md) and read the full ## Versioning section in context
  • Applied code-review lane checks (correctness, cross-file consistency, maintainability) — the "audit-log" and "atomicity" always-checks don't apply to a prose-only README change
  • No findings to post inline

Verdict: no issues found.

Verified independently (not just restating the PR body's own claims):

  • Cross-file consistency: the README's new wording — consumers pin by full commit SHA with a # vX.Y.Z comment, and the pin only moves via a reviewed PR in the consumer's repo — matches how the rest of README.md already describes the model (lines 65, 75, 97: "every consumer's SHA pin," "pins by 40-character commit SHA," "a caller's SHA pin does not cascade").
  • The follow-up claim in "Related" — that .github/workflows/release.yml's header comment carries the same incorrect Dependabot claim — checked directly and confirmed: release.yml#L18-L20 does say "Dependabot bumps them to each new release," so leaving it for a separate PR (to keep this one single-file) is a reasonable scoping call, not an omission.
  • release.yml's patch/minor/major workflow_dispatch claim (unchanged prose, but load-bearing context for the edited paragraph) — confirmed accurate against release.yml#L28.
  • Markdownlint: I could not execute npx markdownlint-cli2 myself — this lane's granted tools are limited to Bash(gh pr diff:*) plus the inline-comment MCP tool, and npx fell outside that grant and required approval that isn't available in this run. I did confirm from .markdownlint-cli2.jsonc that MD013 (line length) is disabled repo-wide, so the rewrapped line lengths in this diff cannot trip lint regardless. The PR body's own markdownlint/git diff --stat/trailing-whitespace claims are therefore author-asserted and unverified by me, not confirmed independently.

No correctness, maintainability, or consistency defects found in the diff itself.
· branch

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9aa1da8dc6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread README.md
@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.

kyle-sexton and others added 2 commits September 8, 2026 12:27
The Versioning rewrite states that consumers are never bumped
automatically, but the Contract's "Pin by SHA" bullet still told
consumers that Dependabot opens weekly bump PRs for these actions.
Scope that bullet: consumers keep this repository out of Dependabot's
`github-actions` updates and repin by reviewed pull request, so a fix
here does not reach them until they repin; Dependabot's `uses:`-only
limitation now applies to the third-party actions a consumer does track.

Also disambiguate the composite pin-lag paragraph, which described this
repository's own Dependabot group moving its self-referencing pins in
wording that read as consumer guidance.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L5ZJnwTRCgc31bmfrdugyU
SECURITY.md still said consumers pick up fixes via an advancing pinned
SHA that Dependabot bumps, and told them to keep the `github-actions`
Dependabot ecosystem enabled. The README's Versioning and Contract
sections say the opposite: consumers keep this repository out of
Dependabot's `github-actions` updates and move the pin by reviewed pull
request, so a fix landed here reaches a consumer only when it repins.
Restate both sentences in those terms and point consumers at this
repository's Releases and the `release-gap-check` advisory issue.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L5ZJnwTRCgc31bmfrdugyU
@kyle-sexton
kyle-sexton merged commit 07c155d into main Sep 8, 2026
70 checks passed
@kyle-sexton
kyle-sexton deleted the docs/versioning-readme-drift branch September 8, 2026 16:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant