Clarify .NET guidelines: distinguish source-breaking vs binary-breaking changes#9687
Open
ronniegeraghty wants to merge 6 commits intoAzure:mainfrom
Open
Conversation
Refine the .NET SDK guidelines to explicitly distinguish between binary-breaking changes (never allowed in minor/patch) and source-breaking changes (permitted in minor releases under specific conditions). This addresses the ambiguity in the current '100% backwards compatible' language. Changes: - docs/dotnet/introduction.md: Replace blanket backwards-compat rule with separate MUST NOT (binary) and MAY (source) rules; add 'Acceptable Source-Breaking Changes' subsection with conditions and C# code example - docs/general/compatibility.md: Add 'Source vs. Binary Compatibility' subsection under API Changes - docs/policies/releasenotes.md: Add 'Source-Breaking Changes' section requiring documentation in release notes Fixes Azure#9517 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ronniegeraghty
requested review from
KrzysztofCwalina,
christothes,
jsquire,
kurtzeborn,
salameer and
weshaggard
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Azure SDK documentation to clarify that .NET binary-breaking changes are disallowed in minor/patch releases, while certain source-breaking changes may be acceptable in minor releases with defined conditions and Architecture Board approval.
Changes:
- Add guidance in .NET versioning docs distinguishing binary-breaking vs. source-breaking changes, including an “acceptable source-breaking changes” checklist and example.
- Add a general “Source vs. Binary Compatibility” subsection to the cross-language compatibility guidelines.
- Add a release-notes policy section requiring source-breaking changes to be documented under “Breaking Changes” with migration guidance.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/policies/releasenotes.md | Adds a policy section for documenting source-breaking changes in release notes. |
| docs/general/compatibility.md | Defines source vs. binary compatibility terminology at the general guidelines level. |
| docs/dotnet/introduction.md | Refines .NET versioning rules to separate binary-breaking vs. source-breaking guidance and adds an example. |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
jsquire
approved these changes
Mar 3, 2026
christothes
reviewed
Mar 3, 2026
- Remove 'new major version' option from binary-breaking guidance per christothes feedback that binary-breaking changes should never happen in existing packages (creating a new package is not a breaking change) - Strengthen wording from 'should happen rarely, if ever' to 'should never be introduced in an existing package' - This also resolves the copilot reviewer's concern about contradictory guidance between 'major version or new package' and the MUST requirement for new packages only Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
christothes
approved these changes
Mar 3, 2026
KrzysztofCwalina
requested changes
Mar 4, 2026
…tions - Define three types of breaking changes: API-breaking, binary-breaking, and source-breaking - Add 'No API-breaking changes' as first condition for acceptable source-breaking changes - Addresses feedback from KrzysztofCwalina in PR review Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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
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
This PR refines the Azure SDK .NET guidelines to explicitly distinguish between binary-breaking changes (never allowed in minor/patch releases) and source-breaking changes (permitted in minor releases under specific conditions with Architecture Board approval).
Problem
The current guidelines state libraries must "be 100% backwards compatible," which implies all breaking changes are prohibited. In practice, the team already makes source-breaking changes (e.g., Azure.Storage.Blobs 12.24.0 → 12.25.0) and considers them acceptable when binary compatibility is preserved. The guidelines need to reflect this reality.
Changes
docs/dotnet/introduction.mdMUST NOT(binary) andMAY(source) rules; add "Acceptable Source-Breaking Changes" subsection with conditions checklist and C# options-bag migration exampledocs/general/compatibility.mddocs/policies/releasenotes.mdConditions for Acceptable Source-Breaking Changes
References