# Breaking Change Definition

This document lists the various types of breaking changes and how to call them out in your code using the [breaking change attributes](./breaking-changes-attribute-help.md).

Breaking changes in cmdlets are defined as follows:

# Cmdlets
- Removing a cmdlet
  - Use the breaking change attribute ["CmdletDeprecationAttribute"](./breaking-changes-attribute-help.md#cmdletdeprecationattribute), more specifically the ["cmdlet deprecation without replacement"](./breaking-changes-attribute-help.md#when-there-is-no-replacement-cmdlet) option
- Changing a cmdlet name without an alias to the original name
  - Use the breaking change attribute ["CmdletDeprecationAttribute"](./breaking-changes-attribute-help.md#cmdletdeprecationattribute), more specifically the ["cmdlet deprecation with replacement"](./breaking-changes-attribute-help.md#when-there-is-a-replacement-cmdlet) option
- Removing or changing a cmdlet alias
  - Use the generic breaking change attribute ["GenericBreakingChangeAttribute"](./breaking-changes-attribute-help.md#genericbreakingchangeattribute) with a [simple message](./breaking-changes-attribute-help.md#with-a-simple-message) calling out the alias that is being deprecated
- Removing a cmdlet attribute option (`SupportShouldProcess`, `SupportsPaging`)
  - Use the generic breaking change attribute ["GenericBreakingChangeAttribute"](./breaking-changes-attribute-help.md#genericbreakingchangeattribute) with a [simple message](./breaking-changes-attribute-help.md#with-a-simple-message) calling out the cmdlet attribute that is being removed
- Breaking change in `OutputType` or removal of `OutputType` attribute
  - Use the cmdlet output type breaking change attribute ["CmdletOutputBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletoutputbreakingchangeattribute)
    - To call out the output type being changed use the above attribute [as described here](./breaking-changes-attribute-help.md#the-output-return-type-is-changing).
    - To deprecate an output type use the above attribute [as described here](./breaking-changes-attribute-help.md#the-output-return-type-is-being-dropped).

# Parameters
- Removing a parameter
  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#a-parameter-is-being-deprecated) to call out a parameter being removed.
- Changing the name of a parameter without an alias to the original parameter name
  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#a-parameter-is-being-replaced) to call out a parameter name change.
- Breaking change in parameter type
  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#a-parameter-is-changing-its-type) to call out a parameter name change.
- Adding a required parameter to an existing parameter set (adding new parameter sets or adding additional optional parameters is not a breaking change)
  - An existing parameter becomes mandatory :
    - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#a-parameter-is-becoming-mandatory) to call out a parameter becoming mandatory.
  - Adding a new mandatory parameter to a parameter set:
      - Use the generic breaking change attribute ["GenericBreakingChangeAttribute"](./breaking-changes-attribute-help.md#genericbreakingchangeattribute) with a [custom message](./breaking-changes-attribute-help.md#with-a-simple-message) calling out the new mandatory parameter that is going to be added to the parameter set.
- Changing parameter order for parameter sets with ordered parameters
    - Use the generic breaking change attribute ["GenericBreakingChangeAttribute"](./breaking-changes-attribute-help.md#genericbreakingchangeattribute) with a [custom message](./breaking-changes-attribute-help.md#with-a-simple-message) calling out the new order in the parameter set.
- Removing or changing a parameter alias
  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#generic-change-in-a-parameter) to call out the change by altering the change description.
- Removing or changing existing parameter attribute values
  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#generic-change-in-a-parameter) to call out the change by altering the change description.
- Making parameter validation more exclusive (_e.g.,_ removing values from a `ValidateSet`)
  - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#generic-change-in-a-parameter) to call out the change by altering the change description.

# Output and Parameter Types
- Changing property names without an accompanying alias to the original name
  - In the output type
    - Use the cmdlet output type breaking change attribute ["CmdletOutputBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletoutputbreakingchangeattribute) [as follows](./breaking-changes-attribute-help.md#a-mixed-example) to call out property name changes (do not specify the attribute property "ReplacementCmdletOutputTypeName" for this purpose).
  - In a parameter
    - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#generic-change-in-a-parameter) to call out the change.
- Removing properties
  - In the output type
      - Use the cmdlet output type breaking change attribute ["CmdletOutputBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletoutputbreakingchangeattribute) [as follows](./breaking-changes-attribute-help.md#a-few-properties-in-the-output-type-are-being-deprecated) to call out deprecated properties. 
  - In a parameter
      - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#generic-change-in-a-parameter) to call out the change.
- Adding additional required properties
  - In the output type
      - Use the cmdlet output type breaking change attribute ["CmdletOutputBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletoutputbreakingchangeattribute) [as follows](./breaking-changes-attribute-help.md#a-few-new-properties-are-being-added-to-the-output-type) to call out deprecated properties. 
  - In a parameter
      - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#generic-change-in-a-parameter) to call out the change.
- Adding required parameters, changing parameter names, or parameter types for methods or constructors
    - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#generic-change-in-a-parameter) to call out the change.
- Changing return types of methods
    - Use the parameter breaking change attribute ["CmdletParameterBreakingChangeAttribute"](./breaking-changes-attribute-help.md#cmdletparameterbreakingchangeattribute) as [described here](./breaking-changes-attribute-help.md#generic-change-in-a-parameter) to call out the change.