ADR 001: Adopt marker-interface exception hierarchy#36
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #36 +/- ##
===========================================
Coverage 100.00% 100.00%
Complexity 60 60
===========================================
Files 9 9
Lines 278 278
===========================================
Hits 278 278
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Records the decision to migrate the bundle (and upstream library) to a marker-interface exception contract: cross-package marker interfaces, concretes extending SPL types, wrap-at-boundary discipline with `$previous` chained, and the controller HTTP-exception exit treated as a documented carve-out. Migration via coordinated 5.0 majors across `itk-dev/openid-connect` and this bundle, sequenced as four PRs. PR 0 (cause-chain bug fixes) already in flight as PR #35. The ADR is self-contained: context, drivers, three options considered, decision, consequences, and references (PSR-18, Symfony's component markers and Psr18Client, Bloch's wrap-at-boundary principle). Status: Draft — awaits team review. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
turegjorup
force-pushed
the
docs/adr-exception-contract-migration
branch
from
4ccd0dd to
f2764ad
Compare
Add a short framing paragraph at the top of "Context" stating that the marker-interface principles the ADR proposes were the intended design all along; the implementation has drifted from intent on specific points and this migration closes those gaps. Co-Authored-By: Claude Opus 4.7 (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.
Summary
Records the architectural decision to migrate the bundle and its upstream
itk-dev/openid-connectlibrary to a marker-interface exception contract, as described inCLAUDE.md's "Exceptions" section.Status: Draft — awaits team review.
What's in this PR
Two new files under
docs/adr/:001-marker-interface-exception-hierarchy.md— the ADR itself: context, drivers, three options considered, the decision and rationale, consequences, and the four-PR migration sequence.README.md— index for future ADRs.No code changes. This PR is documentation only.
Why now
PR #33's review (jekuaitk) surfaced that the bundle's exception handling didn't match the design intent in
CLAUDE.md. Mapping the gap revealed it's deeper than a one-PR fix — neither package has a marker interface, no concrete extends an SPL type, and the bundle and library exception hierarchies have no inheritance link. The ADR captures the decision to fix this properly via coordinated 5.0 majors, rather than continue making local fixes that don't address the underlying contract.Migration sequence (decided in the ADR)
$previous-chain bug fixes, 4.x patch. In flight as PR #35.itk-dev/openid-connect).Review focus
CLAUDE.mdto match current reality)?HttpExceptionsubclasses insrc/Controller/) acceptable as a documented exception to wrap-at-boundary?Approval moves status to Accepted
Once approved, status flips from "Draft" to "Accepted" and implementation can start on PR 1 (upstream library).
🤖 Generated with Claude Code