Skip to content

Add document explaining the different breaking change tool exceptions #3592

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

Jump to bottom
Merged
merged 2 commits into from
Mar 14, 2017
Merged

Add document explaining the different breaking change tool exceptions #3592

merged 2 commits into from
Mar 14, 2017

Conversation

cormacpayne
Copy link
Member

@cormacpayne cormacpayne commented Mar 7, 2017 •
edited
Loading

Description

Add document that outlines each of the exceptions from the breaking change tool, and provide additional information about the scenarios that it flags.

This checklist is used to make sure that common guidelines for a pull request are followed. You can find a more complete discussion of PowerShell cmdlet best practices here.

General Guidelines

  • Title of the pull request is clear and informative.
  • There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.
  • The pull request does not introduce breaking changes (unless a major version change occurs in the assembly and module).

Testing Guidelines

  • Pull request includes test coverage for the included changes.
  • PowerShell scripts used in tests should do any necessary setup as part of the test or suite setup, and should not use hard-coded values for locations or existing resources.

Cmdlet Signature Guidelines

  • New cmdlets that make changes or have side effects should implement ShouldProcess and have SupportShouldProcess=true specified in the cmdlet attribute. You can find more information on ShouldProcess here.
  • Cmdlet specifies OutputType attribute if any output is produced - if the cmdlet produces no output, it should implement a PassThru parameter.

Cmdlet Parameter Guidelines

  • Parameter types should not expose types from the management library - complex parameter types should be defined in the module.
  • Complex parameter types are discouraged - a parameter type should be simple types as often as possible. If complex types are used, they should be shallow and easily creatable from a constructor or another cmdlet.
  • Cmdlet parameter sets should be mutually exclusive - each parameter set must have at least one mandatory parameter not in other parameter sets.

markcowl
markcowl requested changes Mar 11, 2017
View reviewed changes
Copy link
Member

@markcowl markcowl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is awesome. A few minor changes.

documentation/breaking-changes/breaking-changes-tool-help.md Outdated

_The cmdlet '`<cmdlet>`' no longer has output type '`<outputType>`'._

When the output of a cmdlet changes types, that is a breaking change. Existing scripts that assign the output of a cmdlet to a variable and call one of its properties or pass it through to another cmdlet will no longer work.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to work on this? This is not strictly true, if the output type is derived from the original output type, or has the same properties, this would not be a breaking change. Please file an issue for us to triage on fixing this

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have an issue open to do another refactor to the breaking change tool (slated for the May sprint) that includes this change: #3507

documentation/breaking-changes/breaking-changes-tool-help.md Outdated

_The cmdlet '`<cmdlet>`' no longer implements SupportsShouldProcess._

When a cmdlet that previously implemented `SupportsShouldProcess` no longer does, that is a breaking change. Users will no longer be able to use the `WhatIf` and `Confirm` parameters with the cmdlet.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

implement ShouldProcess, in all cases in this one

documentation/breaking-changes/breaking-changes-tool-help.md Outdated

### Description

_The cmdlet '`<cmdlet>`' no longer implements SupportsPaging._
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no longer implements Paging

documentation/breaking-changes/breaking-changes-tool-help.md

### Remediation

_Change the default parameter for cmdlet '`<cmdlet>`' back to '`<parameterSet>`'._
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may want to note that the required parameters in the defautl parameter set and the attributes of those parameters need to remain the same as before - the parameter set proeprties and not the name are important.

documentation/breaking-changes/breaking-changes-tool-help.md Outdated

_The element type for the output has been changed from `'<oldElementType>'` to `'<newElementType>'`._

When the type of the output is an array, and the element type of that array has been changed, that is a breaking change.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably want to mention that types need to have the same proeprties, not necessarily the same names

@markcowl markcowl assigned cormacpayne and unassigned markcowl Mar 11, 2017
@cormacpayne cormacpayne assigned markcowl and unassigned cormacpayne Mar 13, 2017
@markcowl markcowl merged commit 7caf679 into Azure:dev Mar 14, 2017
@cormacpayne cormacpayne deleted the add-breaking-change-doc branch May 8, 2017 16:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@markcowl markcowl markcowl approved these changes

Assignees

@markcowl markcowl

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@cormacpayne @markcowl @msftclas