Upgrading / BC-breaks

[zanbaldwin]

No description provided.

[greptile-apps]

Greptile Summary

The upgraded 6.1 compatibility notes need three documentation corrections: the serialization warning applies only to AbstractIP subclasses, the exception behavior needs clear wording, and the 6to4 entry must identify the full widened detection range.

Confidence Score: 4/5

Safe to merge from a runtime perspective, but the upgrade documentation has three non-blocking accuracy and clarity issues that should be corrected for users upgrading from 6.0.

The verified findings are limited to changelog accuracy and clarity. Source and history comparisons establish the described serialization contract, exception-path change, and widened 6to4 detection behavior.

Files Needing Attention: CHANGELOG.md lines 17-25.

T-Rex Logs

What T-Rex did

• T-Rex produced proofs for the posted P2 findings across multiple reviews.
• The proof-generation script and associated logs were captured and linked to the proofs.
• Contract-validation work assessed the JSON serialization contract and IPv6 handling, with explicit proposals documented.
• A 6to4 detection widening wording was reviewed, and a corresponding changelog entry was drafted.
• Artifacts were organized to support reviewer inspection, tying each activity to concise supporting artifacts.

_{Ran code and verified through T-Rex}

Comments Outside Diff (3)

1. General comment

   Changelog incorrectly says all IpInterface implementors with another jsonSerialize return type break

   • Bug
     • CHANGELOG.md lines 17-18 says that user-space classes implementing IpInterface and returning another type now break. But IpInterface gets serialization through OutputInterface, which only extends untyped \JsonSerializable; neither interface declares jsonSerialize(): string. The concrete string signature exists only on AbstractIP, so the incompatibility applies to subclasses overriding that method, not standalone IpInterface implementors.
   • Cause
     • The documentation conflates the concrete implementation signature in AbstractIP with the inherited JsonSerializable contract exposed through OutputInterface and IpInterface.
   • Fix
     • Replace the claim with wording such as: “A concrete string return type was added to AbstractIP::jsonSerialize(). Subclasses overriding that method with a different return type will now break.”

   _{Ran code and verified through T-Rex}

2. General comment

   Clarify malformed PackingException changelog entry

   • Bug
     • CHANGELOG.md:23 accurately intends to describe an exception-behavior BC break, but “throws a custom strategy's PackingException escape” is ungrammatical and does not clearly identify the escaping exception or the prior wrapper. Users cannot reliably infer which exception to catch after upgrading.
   • Cause
     • The changelog entry was written with an invalid verb/object construction and omits the previous wrapper type.
   • Fix
     • Replace line 23 with: `IPv6::fromEmbedded()` now allows a `PackingException` thrown by a custom strategy to escape instead of wrapping it in `InvalidIpAddressException`.

   _{Ran code and verified through T-Rex}

3. General comment

   Changelog omits the full 6to4 widening scope

   • Bug
     • CHANGELOG.md:24-25 says non-canonical 6to4 addresses are now version-4 values but does not state that Derived::isEmbedded() was widened to all of 2002::/16, including inputs whose trailing 80 bits are nonzero. That condition is the precise behavioral distinction from the preceding implementation.
   • Cause
     • The 6.1 changelog consolidation shortened the original fd52e08 release note, which explicitly documented the complete 2002::/16 range and formerly required zeroed 80-bit tail.
   • Fix
     • Revise CHANGELOG.md:24-25 to identify the whole 2002::/16 range and explicitly say addresses with nonzero bits 48–127 are recognized; retain the existing canonical-packing data-loss note.

   _{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "docs(changelog): 📚 add an upgrading sec..." | Re-trigger Greptile}