| name | breaking-change-check |
| description | Use when adding, removing, or changing any public API surface in this repo (method signatures, class members, interface members, enum values, constructor parameters, or serialization behavior). Guides a systematic backward-compatibility check before committing. |
Breaking Change Safety Check
When to Use
Invoke this skill whenever you are about to:
- Remove or rename a
public or protected method, property, class, or interface
- Change a method signature (parameter types, return type, parameter count, optionality)
- Change a public
enum value or add a new value to a [Flags] enum
- Change a default value that affects serialization or wire behavior
- Modify
TaskOrchestrationContext, TaskActivityContext, DurableTaskClientOptions, or DurableTaskWorkerOptions
Step 1 — Identify the Changed API Surface
Read the file containing the change. List every public or protected member being modified.
For each, determine: is this member shipped in a Microsoft.DurableTask.* NuGet package?
To decide this, inspect src/<area>/<area>.csproj and our build/CI configuration: look for NuGet packaging metadata (such as <PackageId>, IsPackable, GeneratePackageOnBuild, or inclusion in a packing target or release artifact). If the project is packed into a Microsoft.DurableTask.* NuGet, assume customers may depend on it.
Step 2 — Verify All Callers Inside This Repo
For each changed member, search the full solution before modifying the signature:
git grep -n "MemberName" -- '*.cs'
Also search test/ and samples/ — these are first-party consumers that must be updated alongside the change.
Step 3 — Check Orchestration Replay Safety
If the changed API is callable from inside an orchestrator (anything reachable from TaskOrchestrationContext):
- Would the new behavior produce a different result when replaying existing orchestration history?
- If yes: the change is NOT backward-compatible. It requires a new orchestration version (via
TaskVersion) or an explicit feature flag. Do not proceed without documenting this.
Step 4 — Check Serialization Compatibility
If the change affects a type serialized to/from the gRPC wire format or the JSON data converter:
- Adding new optional properties with sensible defaults is generally backward-compatible.
- Removing properties, renaming them, or changing their serialized representation is breaking.
- Inspect
src/Abstractions/Converters/JsonDataConverter.cs for any serializer configuration that applies.
Step 5 — Classify the Breaking Change
Reference: https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md
Classify as one of:
- Binary breaking — existing compiled assemblies will fail to load against the new version
- Source breaking — existing source code will fail to compile against the new version
- Behavioral breaking — existing code compiles and loads but produces different results
Binary and source breaking changes require explicit maintainer approval (noted in PR summary or linked issue).
Behavioral breaking changes on serialization or wire paths require a documented migration plan.
Step 6 — Document in the PR
If the change is breaking (any category), add this block to the PR description:
## Breaking Change
Type: [binary | source | behavioral]
Impact: [what breaks and who is affected]
Migration: [what callers must do to upgrade to this version]
If not breaking, state explicitly: "No breaking change — [reason]."
Common Mistakes in This Repo
- Changing a
DataConverter default in DurableTaskWorkerOptions without noting it affects in-flight orchestrations
- Modifying the
TaskActivityContext abstract interface without updating the source generator output in src/Generators/
- Adding a required constructor parameter to a type registered via DI (breaks existing DI registrations)
- Changing a proto field number or removing a proto field (breaks wire compatibility — field numbers are permanent)
