Breaking Changes Policy

This breaking changes policy is only enforced for libraries which explicitly state it as their governing policy. In certain cases, a library governed by this breaking changes policy may depend on a library which is not governed by the same policy, or which does not provide any breaking changes policy. In those cases, a best-effort is provided to ensure changes to the dependency do not affect dependent code. For maximum long-term compatibility, dependent applications and libraries should treat dependencies not governed by this policy in accordance with the rules described for preliminary features, even though they are not marked as such within the documentation.

Dependencies

With the exception of the items listed in the following table, this library does not depend on any libraries other than the .NET Framework itself. The .NET Framework's breaking changes policy is more strict than this library, and is not anticipated to be the source of any breaking binary or source breaking change which affects the use of this library.

Dependency	Affected Framework(s)	Policy
TaskParallelLibrary	net35-client	This compatibility library is no longer actively developed, and is unlikely to ever change in a manner inconsistent with this breaking changes policy.
Microsoft.Bcl.Build	net40-client, portable-net40	This dependency is compatible with the breaking changes policy since it does not contain any assemblies which are referenced.
Microsoft.Bcl, Microsoft.Bcl.Async	net40-client, portable-net40	Future releases of these dependencies are unlikely to include source-level breaking changes. However, updating to a newer release of these libraries may require one or more assembly binding redirects. To maintain maximum compatibility with this breaking changes policy, the minimum supported version of these dependencies will not change as part of patch releases.

Binary compatible

An assembly x is binary compatible with an assembly y if replacing y with x will not cause an application previously compiled against y to stop functioning at runtime.

Note
Binary compatibility is transitive, but not necessarily symmetric. Specifically, the assembly x may include new APIs that are not included in y; since the application compiled against y is clearly not using any of these new APIs, they do not prevent x from being binary compatible with y.

Source compatible

An assembly x is source compatible with an assembly y if replacing y with x will not cause an application previously compiled against y to encounter build errors when it is recompiled.

Version

A version is comprised of four parts, with the following form.

major.minor.patch.revision

Each part of the version number is an integer in the range 0-65535, inclusive.

Major release

A major release is a release which increments the "major" part of the version.

Minor release

A minor release is a release which increments the "minor" part of the version, but does not change the "major" part.

Patch release

A patch release is a release which increments the "patch" and/or "revision" parts of the version, but does not change either the "major" or "minor" parts.

Preliminary feature

A preliminary feature is a special designation for a publicly-exposed API in the library which is exempted from certain rules within the breaking changes policy for the purpose of improving the agility of library development without compromising reliability for business users primarily interested in API stability.

Stable feature

A stable feature is any type or member within the publicly-exposed API of the library which is not designated as a preliminary feature.

Major and minor releases do not preserve binary compatibility. For dependent assemblies which use a strong name, the binary incompatibility is enforced by a change to the strong name of the assembly. Major and minor releases update the value of the AssemblyVersionAttribute attribute, which always changes the strong name of the assembly.

Minor releases are typically used for the promotion of features previously marked preliminary to stable features of the API.

Major releases are required for any change which breaks backwards compatibility with assembly binding redirection, but are typically used for substantial refactoring or other alterations in order to meet the needs of a broader user base, or for the purpose of improving overall usability or flexibility of the library.

Assembly Binding Redirection for Minor Releases

For this library, minor releases include a special provision for binary compatibility when using assembly binding redirection. For any two versions x and y of the library where the major version of x and y are the same but the minor version of y is greater than the minor version of x, then y is binary compatible with x when assembly binding redirection is used. For more information about using assembly binding redirection, see Redirecting Assembly Versions.

Note
The exceptions described for binary compatibility of patch releases apply for assembly binding redirection as well.

Important
Major releases of this library do not include a special provision for binary compatibility when using assembly binding redirection. Assembly binding redirection should only be used for major releases when the release notes explicitly state that binding redirection is supported for the specific versions in use.

Patch releases preserve binary compatibility for all features of the library which are not marked preliminary. This includes but is not limited to the following guarantees.

Patch releases never change the strong name of the assembly. This means a patch release updates the AssemblyFileVersionAttribute and AssemblyInformationalVersionAttribute values, but does not change the AssemblyVersionAttribute value.
Patch releases do not change the runtime signature of any type or method which is not marked preliminary. The runtime signatures include type and method names
Patch releases may only add elements to the public API of the assembly if they are marked preliminary. This rule ensures that patch releases preserve symmetric binary compatibility for applications and libraries which avoid the use of any feature marked as preliminary.

Revision-Only Releases

In some cases, a release will only update the "revision" part of the version. With regard to this breaking changes policy, these releases are equivalent to patch releases. In practice, revision-only releases are typically reserved for correcting a previous patch or revision release which violated the breaking changes policy, or for correcting a bug which was introduced in the current patch cycle without making changes to the public API of the assembly.

Exceptions

Certain exceptions apply to the binary compatibility requirement of patch releases. These include the following.

All implementation details, i.e. code which is not part of the public API of the assembly, is allowed to change during a patch release. Code using the reflection APIs to manipulate any aspect of the library may observe breaking changes at runtime as a result of changes to implementation details.
All types and members which are marked as preliminary are exempted from the binary compatibility requirement, subject to the rules of preliminary features.

The following table summarizes the intent of various releases.

Release Type	Binary Compatibility	Binding Redirection	Source Compatibility	New Features
Major	Unrestricted	Explicit Only¹	Unrestricted	Unrestricted
Minor	Transitive: Binding Redirection² Symmetric: Unrestricted	Supported	Relaxed Preferred³	Unrestricted
Patch	Transitive: Required Symmetric: Preferred⁴	Implicit⁵	Strict Preferred⁶	Preliminary Only⁴

Release Type

Binary Compatibility

Binding Redirection

Source Compatibility

New Features

Major

Unrestricted

Explicit Only¹

Unrestricted

Minor

Transitive: Binding Redirection²

Symmetric: Unrestricted

Supported

Relaxed Preferred³

Unrestricted

Patch

Transitive: Required

Symmetric: Preferred⁴

Implicit⁵

Strict Preferred⁶

Preliminary Only⁴

Major releases only support assembly binding redirection when explicitly stated in the release notes for a particular major release.
Since minor releases result in a change to the strong name of the assembly, binary compatibility by simply replacing assemblies on disk is never preserved for strong-named applications or libraries which reference the assembly. However, for all stable features, minor releases are binary compatible with previous releases when applications are configured with an assembly binding redirection in their configuration.
To minimize the cost of updating an application to use a new minor release of the library, source-incompatible changes should only be introduced when necessary to support a substantial improvement to the library. Eligible improvements include but are not limited to resource utilization, runtime performance, or new feature offerings.
Restricting the introduction of features in a patch release to preliminary features provides applications the ability to leverage symmetric binary compatibility for maximum runtime reliability, by avoiding the use of any feature which is marked as preliminary.
Assembly binding redirection is only required for compatible assemblies which have different strong names. The binary compatibility requirement for patch releases guarantees that these releases will have the same strong name, so assembly binding redirection is unnecessary.
Changes to preliminary features may result in source code incompatibilities due to situations including but not limited to conflicts due to ambiguous names. In addition, changing the name of a required parameter for the purpose of correcting a spelling error or avoiding confusion is generally allowed due to a very low risk of actually causing compilation problems for users. Changes to the names of optional parameters, on the other hand, should be avoided whenever possible as users are likely to be referencing them directly by name.

This library may include types and/or members which are designated as preliminary features. The preliminary feature designation is indicated by a clear note at the top of the associated documentation page. In the library source code, preliminary features are indicated by including the <preliminary/> element to the XML documentation comment for the feature. While preliminary features are much more "flexible" during the release cycle of the library, certain rules do apply in order to ensure the stronger rules provided for stable features will not be violated by a change to a preliminary feature. The following list includes examples of these rules, but other rules may be imposed by basic logical constraints. The API elements referred to in the following list are assumed to be restricted to the publicly-exposed API of the library. The terms "member" and "members" refer to any method, property, or event.

A member may only refer to a preliminary type in its signature if it is also marked preliminary.
An interface may only include a preliminary member if it is also marked preliminary.
An interface may only extend a preliminary interface if it is also marked preliminary.
A class may only include a preliminary abstract member if either it is also marked preliminary, or all constructors for the class are marked internal. This restriction also applies to abstract classes which do not implement an abstract member declared in a base class.