Skip to content

Update Breaking change contract with ParameterSet names #10099

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
iSazonov wants to merge 2 commits into from
Closed

Update Breaking change contract with ParameterSet names #10099

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e3d6216
Update Breaking change contract with ParameterSet names
iSazonov Jul 11, 2019
9b372a5
Add ParameterSet in spelling
iSazonov Jul 11, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .spelling
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -474,6 +474,7 @@ packagemanagement
parameterbinderbase
parameterbindercontroller
parameterbinding
parameterset
pathresolution
patochun
patwardhan
Expand Down
37 changes: 25 additions & 12 deletions docs/dev-process/breaking-change-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Breaking Changes
# Breaking Change Contract

## 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).

Expand All @@ -14,11 +16,11 @@ To help triage breaking changes, we classify them in to four buckets:
1. Unlikely Grey Area
1. Clearly Non-Public

## Bucket 1: Public Contract
### Bucket 1: Public Contract

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

### Unacceptable changes
#### Unacceptable changes

+ A code change that results in a change to the existing behavior observed for a given input with an API, protocol or the PowerShell language.
+ Renaming or removing a public type, type member, or type parameter; renaming or removing a cmdlet or cmdlet parameter (note: it is possible to rename a cmdlet parameter if a parameter alias is added.
Expand All @@ -30,28 +32,34 @@ This is an acceptable solution for PowerShell scripts but may break .NET code th
+ Example: A cmdlet with a parameter -p1 that was previously type as [object] cannot be changed to be or a more restrictive type such as [int].
+ Making an incompatible change to any protocol without increasing the protocol version number.

### Acceptable changes
#### Acceptable changes

+ Any existing behavior that results in an error message generally may be changed to provide new functionality.
+ A new instance field is added to a type (this impacts .NET serialization but not PowerShell serialization and so is considered acceptable.)
+ Adding new types, new type members and new cmdlets
+ Making changes to the protocols with a protocol version increment. Older versions of the protocol would still need to be maintained to allow communication with earlier systems. This would require that protocol negotiation take place between the two systems. In addition to any protocol code changes, the Microsoft Open Specification program requires that the formal protocol specification for a protocol be updated in a timely manner. An example of a MS protocol specification document (MS-PSRP) can be found at: https://msdn.microsoft.com/library/mt242417.aspx
+ Making changes to the protocols with a protocol version increment.
Older versions of the protocol would still need to be maintained to allow communication with earlier systems.
This would require that protocol negotiation take place between the two systems.
In addition to any protocol code changes, the Microsoft Open Specification program requires that the formal protocol specification for a protocol be updated in a timely manner.
An example of a MS protocol specification document (MS-PSRP) can be found at: https://msdn.microsoft.com/library/mt242417.aspx

## Bucket 2: Reasonable Grey Area
### Bucket 2: Reasonable Grey Area

Change of behavior that customers would have reasonably depended on.

Examples:

+ Change in timing/order of events (even when not specified in docs)
+ Example: PowerShell events are handled by interleaving their execution with the execution of the main pipeline thread. Where and when this interleaving occurs might change. This order of execution is not specified but is deterministic so changing it might break some scripts.
+ Example: PowerShell events are handled by interleaving their execution with the execution of the main pipeline thread. Where and when this interleaving occurs might change.
This order of execution is not specified but is deterministic so changing it might break some scripts.
+ Change in parsing of input and throwing new errors (even if parsing behavior is not specified in the docs)
+ Example: a script may be using a JSON parser that is forgiving to minor syntactic errors in the JSON text. Changing that parser to be more rigorous in its processing would result in errors being thrown when no error was generated in the past thus breaking scripts.
+ Example: a script may be using a JSON parser that is forgiving to minor syntactic errors in the JSON text.
Changing that parser to be more rigorous in its processing would result in errors being thrown when no error was generated in the past thus breaking scripts.

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
### Bucket 3: Unlikely Grey Area

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

Expand All @@ -61,11 +69,12 @@ Examples:

+ Example: the existing behavior of the PowerShell cd called without arguments is to do nothing. Changing this behavior to be consistent with UNIX shells which typically set the CWD to the user’s home directory

+ Example: changes to formatting for an object type. We have always considered the output formatting of an object to be a user experience issue and thus open for change. Since PowerShell pipes objects not text, changes to the way an object is rendered to text is generally considered to be allowed.
+ Example: changes to formatting for an object type. We have always considered the output formatting of an object to be a user experience issue and thus open for change.
Since PowerShell pipes objects not text, changes to the way an object is rendered to text is generally considered to be allowed.

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

## Bucket 4: Clearly Non-Public
### Bucket 4: Clearly Non-Public

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

Expand All @@ -76,11 +85,15 @@ 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
### What This Means for Contributors

+ All bucket 1, 2, and 3 breaking changes require contacting team at @powershell/powershell.
+ If you're not sure into which bucket a given change falls, contact us as well.
+ It doesn't matter if the existing behavior is "wrong", we still need to think through the implications. PowerShell has been in broad use for over 10 years so we be must be extremely sensitive to breaking existing users and scripts.
+ If a change is deemed too breaking, we can help identify alternatives such as introducing a new API or cmdlet and obsoleting the old one.

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

## Clearly non-breaking changes

+ ParameterSet names are not a public api and changing them is not a breaking change.