Document target-hop and dependencies: rules in kind: rubric (closes #76)#97
Open
JuanVqz wants to merge 2 commits into
Open
Document target-hop and dependencies: rules in kind: rubric (closes #76)#97JuanVqz wants to merge 2 commits into
JuanVqz wants to merge 2 commits into
Conversation
JuanVqz
added a commit
that referenced
this pull request
May 5, 2026
Three minor refinements per review of CLAUDE.md kind: rubric: 1. Split SCOPE_WITHOUT_LAMBDA example off the target-hop paragraph onto its own line for scannability. 2. Reframe check: true / check: false explanation. The flag is editorial advice about broad applicability, not a per-app determination. A check: false bridge gem still becomes effectively required for a specific app that triggers its rescued breaking pattern. Per-app applicability is driven by the per-pattern fix: field, not the flag. 3. Add explicit note that bin/validate-patterns does not enforce the dependencies: ↔ kind relationship — it's editorial guidance for authors and reviewers, not schema. Pre-empts future "why doesn't validate-patterns check this?" questions. Refs #53, refs #76
Two implicit rules from the issue #53 rollout that were never written down. Surfaced during reviews of #73 (rails-40 SCOPE_WITHOUT_LAMBDA borderline) and #74 (rails-50 dependencies semantics). 1. **Target-hop rule** — judge kind at the target hop, not the API's historical timeline. Each rails-XY-patterns.yml file is a statement about that specific hop. The same API can be deprecation in rails-31-patterns.yml and breaking in rails-40-patterns.yml. Added as a paragraph above the four-value list, with the concrete example of SCOPE_WITHOUT_LAMBDA. 2. **dependencies: ↔ kind relationship** — added a new section "## How the dependencies: section relates to kind" documenting that dependencies: serves TWO purposes: - Bridge gems for breaking patterns (e.g. protected_attributes rescues attr_accessible) - New-default / new-recommended gems Rails introduces (e.g. bootsnap, propshaft, the solid_* family) The original #76 framing said dependencies is only relevant to breaking. That's too strong — actual data across the 12 pattern files shows both purposes. Used the accurate two-purpose framing. Also explains check: true vs check: false. Doc-only. No code changes. No pattern reclassifications. Refs #53, closes #76
Three minor refinements per review of CLAUDE.md kind: rubric: 1. Split SCOPE_WITHOUT_LAMBDA example off the target-hop paragraph onto its own line for scannability. 2. Reframe check: true / check: false explanation. The flag is editorial advice about broad applicability, not a per-app determination. A check: false bridge gem still becomes effectively required for a specific app that triggers its rescued breaking pattern. Per-app applicability is driven by the per-pattern fix: field, not the flag. 3. Add explicit note that bin/validate-patterns does not enforce the dependencies: ↔ kind relationship — it's editorial guidance for authors and reviewers, not schema. Pre-empts future "why doesn't validate-patterns check this?" questions. Refs #53, refs #76
JuanVqz
force-pushed
the
feature/document-target-hop-and-dependencies-rules
branch
from
5e26ed6 to
fb413d0
Compare
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
Closes #76. Documents two rules in
CLAUDE.md's## Assigning kind:section that have been implicit in the rollout but never written down:kindat the target hop, not the API's historical timeline.dependencies:↔kindrelationship: when thedependencies:block applies and to which kinds.Doc-only PR. No code changes. No pattern reclassifications.
What changed
Target-hop rule (added inside
## Assigning kind:)A new paragraph above the four-value list states that each
rails-XY-patterns.ymlfile is a statement about that hop — what changes when the user upgrades INTO that version. The same API can bedeprecationinrails-31-patterns.ymlandbreakinginrails-40-patterns.yml. Concrete example called out:SCOPE_WITHOUT_LAMBDA(deprecated in Rails 3.1, raises in 4.0 → classifiedbreakinginrails-40-patterns.yml).This was the recurring source of "but it was deprecated earlier!" arguments during the classification reviews. The rule is consistent with how the patterns are already organized — one file per hop — but it wasn't written down.
New section:
## How the dependencies: section relates to kindAdded immediately after the four-value rubric. Documents that the
dependencies:block serves two distinct purposes, not one:breakingpatterns — e.g.,protected_attributesrescuesattr_accessible,respondersrescuesrespond_with,rails-controller-testingrescuesassigns/assert_template. Abreakingpattern with a corresponding bridge entry is a softenable break.bootsnap(5.2),propshaft(8.0),solid_cache/solid_queue/solid_cable(8.0),kamal(8.0),bundler-audit(8.1). These pair withoptionalpatterns or with no pattern at all.The original issue #76 framed
dependencies:as "only relevant tobreaking". That's too strong — the actual data across the 12 pattern files shows new-default gems (typicallyoptional) also live independencies:. The PR uses the more accurate two-purpose framing.The
check: true/check: falseflag is also explained: roughly "you should add this" vs "you may add this".Files changed (2 files, +23 lines)
CLAUDE.md— target-hop paragraph + new## How the dependencies: section relates to kindsectionrails-upgrade/CHANGELOG.md— Unreleased entryTest plan
bin/validate-patterns(all 12 files) still passes — no schema changes, doc-onlyLinked issues
kind:field to detection patterns; renamebreaking_changes:→upgrade_findings:#53 (parent rollout — this is a doc-cleanup follow-up surfaced during PR Classify kind: for rails-40-patterns.yml (#55) #73 and PR Classify kind: for rails-50-patterns.yml (#58) #74 reviews)Out of scope
kind:value (the rule existed implicitly; this PR just writes it down)