diff --git a/.spelling b/.spelling index 92f4ee57345..97399d5f5ab 100644 --- a/.spelling +++ b/.spelling @@ -474,6 +474,7 @@ packagemanagement parameterbinderbase parameterbindercontroller parameterbinding +parameterset pathresolution patochun patwardhan diff --git a/docs/dev-process/breaking-change-contract.md b/docs/dev-process/breaking-change-contract.md index f33f806f7e8..c9c4f393e69 100644 --- a/docs/dev-process/breaking-change-contract.md +++ b/docs/dev-process/breaking-change-contract.md @@ -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). @@ -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. @@ -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. @@ -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. @@ -76,7 +85,7 @@ 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. @@ -84,3 +93,7 @@ revisit such change if there's too much pain inflicted on the ecosystem through + 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.