Document the BC-change attributes and per-change compatibility guides#2374
Draft
Jonas Elfering (keulinho) wants to merge 2 commits into
Draft
Document the BC-change attributes and per-change compatibility guides#2374Jonas Elfering (keulinho) wants to merge 2 commits into
Jonas Elfering (keulinho) wants to merge 2 commits into
Conversation
…guides Planned changes to symbols that stay are no longer marked with @deprecated reason:* notes but announced via the BCChange attribute family. Document every attribute, who is affected (call sites vs extending classes), which changes can safely be opted into today, and how to write extension code that is compatible with the current and the next major version at the same time. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Developer Docs healthcheckStatus: Completed with |
…bute Restructure the quick guides from two audience-grouped lists into one guide per attribute, each stating explicitly what call sites and what extending classes need to do — including the "nothing to do" cases with the variance reasoning, so both audiences can check every announcement against their code. Co-Authored-By: Claude Fable 5 <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
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
The backward-compatibility guidelines still describe planned API changes (return type changes, new parameters, becoming final, …) as
@deprecatedannotations withreason:*notes. Since shopware/shopware#17798, such changes on symbols that stay are announced with dedicated PHP attributes fromShopware\Core\Framework\Deprecation\BCChangeinstead, and a PHPStan rule forbids newreason:*markers.This updates the page accordingly:
@deprecatedsection: clarifies it is only for symbols that actually go away; planned changes use the attributes.CallSiteCompatibilityChange/ExtenderCompatibilityChangeaudience interfaces, and the PHPStan validation behind it.@deprecated/Feature::isActivestyle to the current#[NewRequiredParameter]+ conditional runtime deprecation pattern, including the note that framework-invoked#[Route]methods must not trigger it.Related links
Checklist
PageRefreferences where relevant..gitbook.yamlif pages were moved, renamed, or deleted. (no pages moved).wordlist.txt(and sorted it) if spellcheck flags new legitimate terms.Notes
Draft until the platform PR stack (17979 → 17985 → 17992 → 18011) is merged, since the page documents behavior those PRs introduce. Attribute names, constructor signatures, and validation semantics were taken directly from the implementation.
🤖 Generated with Claude Code