Add a decision for opt-in breaking changes #491
Conversation
Documentation Deployment CompleteYour documentation preview has been successfully deployed! Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-491/ |
team/DECISIONS.md
Outdated
|
|
||
| Strict semver adherence can slow SDK development when the breaking change only affects users who explicitly adopt new functionality. If existing code paths remain unaffected, the practical impact on users is minimal. | ||
|
|
||
| For example, converting a `TypedDict` to `total=False` is technically breaking if existing implementations don't provide the new optional members. However, if the only way to encounter those new members is by adding a new tool that uses the new format, the change is effectively "pay for play." Users who don't adopt the new tool never observe the break. |
There was a problem hiding this comment.
Up until this point, I was just thinking "that's how backwards compatibility works" :P
But this makes sense. We have done something similar with Bidirectional Agents and tool context for example. We have started to pass in Bidi Agent as Agent. This is "technically" backwards compatible, but it's pay for play
team/DECISIONS.md
Outdated
|
|
||
| Strict semver adherence can slow SDK development when the breaking change only affects users who explicitly adopt new functionality. If existing code paths remain unaffected, the practical impact on users is minimal. | ||
|
|
||
| For example, converting a `TypedDict` to `total=False` is technically breaking if existing implementations don't provide the new optional members. However, if the only way to encounter those new members is by adding a new tool that uses the new format, the change is effectively "pay for play." Users who don't adopt the new tool never observe the break. |
There was a problem hiding this comment.
It might just be me but I feel this explanation is slightly confusing.
For example, converting a
TypedDicttototal=Falseis technically breaking if existing implementations don't provide the new optional members
I think I understand that you mean to say if a previously required field now becomes optional, existing code paths expecting the field would break if not provided. I just wonder if there is a more direct way to say this.
There was a problem hiding this comment.
I concur; the example isn't clear at all; the problem is on the reading side, not the producing side. Updating the example
Documentation Deployment CompleteYour documentation preview has been successfully deployed! Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-491/ |
|
/strands review |
|
Assessment: Approve ✅ This decision record is well-written and follows the established structure in Key Observations:
The updated example (addressing pgrayy's feedback) now clearly distinguishes between the producing side vs. reading side of the breaking change, making the concept more understandable. Nice addition to the decision record! 🎉 |
Documentation Deployment CompleteYour documentation preview has been successfully deployed! Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-491/ |
1 similar comment
Documentation Deployment CompleteYour documentation preview has been successfully deployed! Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-491/ |
7 participants
Add a record of the decision that "opt-in breaking changes" being acceptable from an SDK evolution strategy.
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.