"Fossies" - the Fresh Open Source Software Archive

Member "PowerShell-7.2.5/docs/dev-process/breaking-change-contract.md" (21 Jun 2022, 6258 Bytes) of package /linux/misc/PowerShell-7.2.5.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.


Breaking Changes

We have a serious commitment to backwards compatibility with all earlier versions of PowerShell – including the language, cmdlets, APIs and the various protocols (e.g. PowerShell Remoting Protocol) and data formats (e.g. cdxml).

Below is a summary of our approach to handing breaking changes including what kinds of things constitute breaking changes, how we categorize them, and how we decide what we're willing to take.

Note that these rules only apply to existing stable features that have shipped in a supported release. New features marked as “in preview” that are still under development may be modified from one preview release to the next. These are not considered breaking changes.

To help triage breaking changes, we classify them in to four buckets:

  1. Public Contract
  2. Reasonable Grey Area
  3. Unlikely Grey Area
  4. Clearly Non-Public

Bucket 1: Public Contract

Any change that is a clear violation of the public contract.

Unacceptable changes

This is an acceptable solution for PowerShell scripts but may break .NET code that depends on the name of the original member on the cmdlet object type.)

Acceptable changes

Bucket 2: Reasonable Grey Area

Change of behavior that customers would have reasonably depended on.

Examples:

Judiciously making changes in these type of features require judgement: how predictable, obvious, consistent was the behavior? In general, a significant external preview of the change would need to be done also possibly requiring an RFC to be created to allow for community input on the proposal.

Bucket 3: Unlikely Grey Area

Change of behavior that customers could have depended on, but probably wouldn't.

Examples:

As with type 2 changes, these require judgement: what is reasonable and what’s not?

Bucket 4: Clearly Non-Public

Changes to surface area or behavior that is clearly internal or non-breaking in theory, but breaks an app.

Examples:

It is impossible to evolve a code base without making such changes, so we don't require up-front approval for these, but we will sometimes have to go back and revisit such change if there's too much pain inflicted on the ecosystem through a popular app or library.

What This Means for Contributors

Request for clarifications or suggested alterations to this document should be done by opening issues against this document.