Add StaticAnalysis doc and improve build message #5351
Conversation
maddieclayton
changed the title
|
failed build looks like this: https://azuresdkci.westus2.cloudapp.azure.com/job/powershell/1682/console |
| Our StaticAnalysis tools help us ensure our modules follow PowerShell guidelines and prevent breaking changes from occurring outside of breaking change releases. | ||
|
|
||
| - [How to know if you have a StaticAnalysis Error](#how-to-know-if-you-have-a-staticanalysis-error) | ||
| - [Where to find StaticAnalysis reports](#where-to-find-staticsanalysis-reports) |
There was a problem hiding this comment.
@maddieclayton typo in the hyperlink:
#where-to-find-staticsanalysis-reports
There was a problem hiding this comment.
Done, good catch
| We take breaking changes very seriously, so please be mindful about the violations that you suppress in our repo. | ||
|
|
||
| ### Signature Issues | ||
| Signature issues occur when your cmdlets do not follow PowerShell standards. Please check [this page](https://github.com/Azure/azure-powershell/wiki/PowerShell-Cmdlet-Design-Guidelines) to ensure you are following PowerShell guidelines. Issues with severity 0 or 1 must be addressed, while issues with severity 2 are advisory. If you have an issue with severity 0 or 1 that have been approved by the Azure PowerShell team, you can suppress them following these steps: |
There was a problem hiding this comment.
@maddieclayton nit: If you have an issue with severity 0 or 1 that has been approved by the Azure PowerShell team...
|
|
||
| ### Breaking Changes | ||
| If you make a change that could cause a breaking change, it will be listed in BreakingChangeIssues.csv. Please look at each of these errors, and if they do indeed introduce a breaking change in a non-breaking change release, please revert the change that caused this violation. Sometimes the error listed in the .csv file can be a false positive (for example, if you change a parameter attribute to span all parameter sets rather than individual parameter sets). Please read the error thoroughly and examine the relevant code before deciding that an error is a false positive, and contact the Azure PowerShell team if you have questions. If you are releasing a preview module, are releasing during a breaking change release, or have determined that the error is a false positive, please follow these instructions: | ||
| - Navigate to the [BreakingChangeIssues.csv file](https://github.com/Azure/azure-powershell/blob/preview/tools/StaticAnalysis/Exceptions/BreakingChangeIssues.csv) in our repo. |
There was a problem hiding this comment.
@maddieclayton I'd reorder these steps (for both Breaking Changes and Signature Issues) so that the user knows to copy the contents from the build .csv file first and then open the repository .csv file.
I would also call out that you need to open these .csv files and edit them in a text editor (such as VS Code). Opening them and copying/pasting the lines use Excel will cause parsing errors during StaticAnalysis.
Description
#3037
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
Testing Guidelines
Cmdlet Signature Guidelines
ShouldProcessand haveSupportShouldProcess=truespecified in the cmdlet attribute. You can find more information onShouldProcesshere.OutputTypeattribute if any output is produced - if the cmdlet produces no output, it should implement aPassThruparameter.Cmdlet Parameter Guidelines