|
1 | | -# Contribute Code or Provide Feedback |
| 1 | +# Contribute Code or Provide Feedback for Azure PowerShell |
| 2 | + |
| 3 | +This repository contains a set of PowerShell cmdlets for developers and administrators to develop, deploy, and manage Microsoft Azure applications. |
| 4 | + |
| 5 | +## Basics |
2 | 6 |
|
3 | 7 | If you would like to become an active contributor to this project please follow the instructions provided in [Microsoft Azure Projects Contribution Guidelines](http://azure.github.io/guidelines/). |
4 | 8 |
|
5 | | -If you encounter any bugs with Microsoft Azure PowerShell please file an issue in the [Issues](https://github.com/Azure/azure-powershell/issues) section of the project. |
| 9 | +In the Azure Developer Experience, you are at Step 5: |
| 10 | + |
| 11 | +[API Design Review](https://github.com/Azure/adx-documentation-pr#begin-api-design-review) -> [Engage with ADX team](https://github.com/Azure/adx-documentation-pr/blob/master/README.md#engage-with-adx-team) -> [Swagger specification](https://github.com/Azure/adx-documentation-pr#create-swagger-specification) -> [SDKs](https://github.com/Azure/adx-documentation-pr#sdks) -> _**[CLIs](https://github.com/Azure/adx-documentation-pr#clis)**_ |
| 12 | + |
| 13 | +## Table of Contents |
| 14 | + |
| 15 | +[Before Starting](#before-starting) |
| 16 | +- [Onboarding](#onboarding) |
| 17 | +- [GitHub Basics](#github-basics) |
| 18 | + - [GitHub Workflow](#github-workflow) |
| 19 | + - [Forking the Azure/azure-powershell repository](#forking-the-azureazure-powershell-repository) |
| 20 | +- [Code of Conduct](#code-of-conduct) |
| 21 | + |
| 22 | +[Filing Issues](#filing-issues) |
| 23 | + |
| 24 | +[Making Changes](#making-changes) |
| 25 | +- [Pull Requests](#pull-requests) |
| 26 | +- [SDK for .NET](#sdk-for-net) |
| 27 | +- [Pull Request Guidelines](#pull-request-guidelines) |
| 28 | + - [Cleaning up commits](#cleaning-up-commits) |
| 29 | + - [General guidelines](#general-guidelines) |
| 30 | + - [Testing guidelines](#testing-guidelines) |
| 31 | + - [Cmdlet signature guidelines](#cmdlet-signature-guidelines) |
| 32 | + - [Cmdlet parameter guidelines](#cmdlet-parameter-guidelines) |
| 33 | + - [Cmdlet pipeline guidelines](#cmdlet-pipeline-guidelines) |
| 34 | + |
| 35 | +## Before Starting |
| 36 | + |
| 37 | +### Onboarding |
| 38 | + |
| 39 | +Make sure that your GitHub account is part of the Azure organization. [Use this page](http://aka.ms/azuregithub) to link your account. |
| 40 | + |
| 41 | +Before cloning this repository, please make sure you have started in our [documentation repository](https://github.com/Azure/adx-documentation-pr) (you will only have access to that page if you are part of the Azure organization). |
| 42 | + |
| 43 | +### GitHub Basics |
| 44 | + |
| 45 | +#### GitHub Workflow |
| 46 | + |
| 47 | +If you don't have experience with Git and GitHub, some of the terminology and process can be confusing. [Here is a guide to understanding the GitHub flow](https://guides.github.com/introduction/flow/) and [here is a guide to understanding the basic Git commands](https://services.github.com/kit/downloads/github-git-cheat-sheet.pdf). |
| 48 | + |
| 49 | +#### Forking the Azure/azure-powershell repository |
| 50 | + |
| 51 | +Unless you are working with multiple contributors on the same file, we ask that you fork the repository and submit your pull request from there. [Here is a guide to forks in GitHub](https://guides.github.com/activities/forking/). |
| 52 | + |
| 53 | +### Code of Conduct |
| 54 | + |
| 55 | +This project has adopted the [Microsoft Open Source Code of Conduct ](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
| 56 | + |
| 57 | +## Filing Issues |
| 58 | + |
| 59 | +You can find all of the issues that have been filed in the [Issues](https://github.com/Azure/azure-powershell/issues) section of the repository. |
| 60 | + |
| 61 | +If you encounter any bugs with Microsoft Azure PowerShell, please file an issue [here](https://github.com/Azure/azure-powershell/issues/new) and make sure to fill out the provided template with the requested information. |
| 62 | + |
| 63 | +To suggest a new feature or changes that could be made to Azure PowerShell, file an issue the same way you would for a bug, but remove the provided template and replace it with information about your suggestion. |
| 64 | + |
| 65 | +You can find the code complete and release dates of the next three Azure PowerShell releases in the [Milestones](https://github.com/Azure/azure-powershell/milestones) section of the Issue page. Each milestone will display the issues that are being worked on for the corresponding release. |
| 66 | + |
| 67 | +## Making Changes |
| 68 | + |
| 69 | +### Pull Requests |
| 70 | + |
| 71 | +You can find all of the pull requests that have been opened in the [Pull Request](https://github.com/Azure/azure-powershell/pulls) section of the repository. |
| 72 | + |
| 73 | +To open your own pull request, click [here](https://github.com/Azure/azure-powershell/compare). When creating a pull request, keep the following in mind: |
| 74 | +- Make sure you are pointing to the fork and branch that your changes were made in |
| 75 | +- Choose the correct branch you want your pull request to be merged into |
| 76 | + - The **dev** branch is for active development; changes in this branch will be in the next Azure PowerShell release |
| 77 | + - The **master** branch contains a snapshot of the source code at the time of the last release |
| 78 | + - The **release-X.X.X** branch is for active development during a release |
| 79 | +- The pull request template that is provided **should be filled out**; this is not something that should just be deleted or ignored when the pull request is created |
| 80 | + - Deleting or ignoring this template will elongate the time it takes for your pull request to be reviewed |
| 81 | +- The SLA for reviewing pull requests is **two business days** |
| 82 | + |
| 83 | +### SDK for .NET |
| 84 | + |
| 85 | +Before making any changes to the Azure PowerShell repository, the corresponding NuGet packages must have been published from the [Azure SDK for .NET](https://github.com/Azure/azure-sdk-for-net) repository. |
| 86 | + |
| 87 | +For more information on how to make changes to the SDK for .NET repository and publish the corresponding packages to NuGet, click [here](https://github.com/Azure/azure-sdk-for-net/blob/AutoRest/README.md). |
| 88 | + |
| 89 | +### Pull Request Guidelines |
| 90 | + |
| 91 | +A pull request template will automatically be included as a part of your PR. Please fill out the checklist as specified. Pull requests **will not be reviewed** unless they include a properly completed checklist. |
| 92 | + |
| 93 | +The following is a list of guidelines that pull requests opened in the Azure PowerShell repository must adhere to. You can find a more complete discussion of PowerShell cmdlet best practices [here](https://msdn.microsoft.com/en-us/library/dd878270(v=vs.85).aspx). |
| 94 | + |
| 95 | +#### Cleaning up Commits |
| 96 | + |
| 97 | +If you are thinking about making a large change to your Azure PowerShell cmdlets, **break up the change into small, logical, testable chunks, and organize your pull requests accordingly**. |
| 98 | + |
| 99 | +Often when a pull request is created with a large number of files changed and/or a large number of lines of code added and/or removed, GitHub will have a difficult time opening up the changes on their site. This forces the Azure PowerShell team to uses separate software, such as CodeFlow or Beyond Compare, to do a code review on the pull request. |
| 100 | + |
| 101 | +If you find yourself creating a pull request and are unable to see all the changes on GitHub, we recommend **splitting the pull request into multiple pull requests that are able to be reviewed on GitHub**. |
| 102 | + |
| 103 | +If splitting up the pull request is not an option, we recommend **creating individual commits for different parts of the pull request, which can be reviewed individually on GitHub**. |
| 104 | + |
| 105 | +For more information on cleaning up the commits in a pull request, such as how to rebase, squash, and cherry-pick, click [here](./documentation/cleaning-up-commits.md). |
| 106 | + |
| 107 | +#### General guidelines |
| 108 | + |
| 109 | +The following guidelines must be followed in **EVERY** pull request that is opened. |
| 110 | + |
| 111 | +- Title of the pull request is clear and informative |
| 112 | +- There are a small number of commits that each have an informative message |
| 113 | +- A description of the changes the pull request makes is included, and a reference to the bug/issue the pull request fixes is included, if applicable |
| 114 | +- All files have the Microsoft copyright header |
| 115 | +- Cmdlets refer to the management libraries through NuGet references - no dlls are checked in |
| 116 | +- The pull request does not introduce [breaking changes](https://github.com/markcowl/azure-powershell/blob/doc1/documentation/changes.md#breaking-change-definition) (unless a major version change occurs in the assembly and module) |
| 117 | + |
| 118 | +#### Testing guidelines |
| 119 | + |
| 120 | +The following guidelines must be followed in **EVERY** pull request that is opened. |
| 121 | + |
| 122 | +- Pull request includes test coverage for the included changes |
| 123 | +- Tests must use xunit, and should either use Moq to mock management client calls, or use the scenario test framework |
| 124 | +- Test code should not contain hard coded values for resource names, resource locations, subscriptions, tenants, or similar values. Test scripts, when run live, should be executable using any subscription and any location in Azure |
| 125 | +- PowerShell scripts used in tests must do any necessary setup as part of the test or suite setup, and should not use hard-coded values for existing resources |
| 126 | +- Test should not use App.config files for settings |
| 127 | +- Tests should use the built-in PowerShell functions for generating random names when unique names are necessary - this will store names in the test recording |
| 128 | +- Tests should use `Start-Sleep` to pause rather than `Thread.Sleep` |
| 129 | + |
| 130 | +#### Cmdlet signature guidelines |
| 131 | + |
| 132 | +The following guidelines must be followed in pull requests that add, edit, or remove a cmdlet. |
| 133 | + |
| 134 | +- Cmdlet name uses an approved PowerShell verb - use enums for `VerbsCommon`, `VerbsCommunication`, `VerbLifecycle`, `VerbsOther` whenever possible |
| 135 | +- Cmdlet noun name uses the AzureRm prefix for management cmdlets, and the Azure prefix for data plane cmdlets |
| 136 | +- Cmdlet specifies the `OutputType` attribute if any output is produced; if the cmdlet produces no output, it should implement a `PassThrough` parameter |
| 137 | +- If the cmdlet makes changes or has side effects, it should implement `ShouldProcess` and have `SupportsShouldProcess = true` specified in the cmdlet attribute. See a discussion about correct `ShouldProcess` implementation [here](https://gist.github.com/markcowl/338e16fe5c8bbf195aff9f8af0db585d#what-is-the-change). |
| 138 | +- Cmdlets should derive from AzureRmCmdlet for management cmdlets, and AzureDataCmdlet for data cmdlets |
| 139 | +- If multiple parameter sets are implemented, the cmdlet should specify a `DefaultParameterSetName` in its cmdlet attribute |
| 140 | + |
| 141 | +#### Cmdlet parameter guidelines |
| 142 | + |
| 143 | +The following guidelines must be followed in pull requests that add, edit, or remove a parameter. |
| 144 | + |
| 145 | +- Cmdlets should have no more than four positional parameters |
| 146 | +- Cmdlet parameter sets should be mutually exclusive - each parameter set must have at least one mandatory parameter not in other parameter sets |
| 147 | +- Parameter types should not expose types from the management library - complex parameter types should be defined in the module |
| 148 | +- 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 |
| 149 | +- Parameters should be explicitly marked as `Mandatory` or not, and should contain a `HelpMessage` |
| 150 | +- No parameter is of type `object` |
| 151 | +- Management cmdlets should have the following parameters and aliases: |
| 152 | + - `ResourceGroupName` with (optional) alias to `ResourceGroupName` type `string` marked as `[ValueFromPipelineByPropertyName]` |
| 153 | + - `Name` with alias to `ResourceName` type `string` marked as `[ValueFromPipelineByPropertyName]` |
| 154 | + - `Location` (if appropriate) type `string` |
| 155 | + - `Tag` type `HashTable` |
| 156 | + |
| 157 | +#### Cmdlet pipeline guidelines |
| 158 | + |
| 159 | +The following guidelines must be followed in pull requests that make changes to pipeline parameters. |
| 160 | + |
| 161 | +- Complex parameters should take values from the pipeline when possible, and certainly when they match the output type of another cmdlets |
| 162 | +- Only one parameter should use `ValueFromPipeline` per parameter set; parameters from different parameter sets may have this attribute, but should not be convertible |
| 163 | +- No parameter is of type `object` |
| 164 | +- Each management cmdlet should have a parameter set that takes `ResourceGroupName` and `Name` from the pipeline by property value |
| 165 | +- For a given resource type, it should be possible to pipe the output of `Get` and `New` cmdlets to the input of `Set`, `Update`, `Remove` and other action cmdlets for that resource |
0 commit comments