Skip to content

Latest commit

 

History

History
161 lines (115 loc) · 8.03 KB

CONTRIBUTING.md

File metadata and controls

161 lines (115 loc) · 8.03 KB
Raw

Contributing to Azure PowerShell

This repository contains PowerShell cmdlets for developers and administrators to develop, deploy, administer, and manage Microsoft Azure resources.

Basics

If you would like to become a contributor to this project (or any other open source Microsoft project), see how to Get Involved.

Before Starting

Onboarding

All users must sign the Microsoft Contributor License Agreement (CLA) before making any code contributions. For Microsoft employees, make sure that your GitHub account is part of the Azure organization. Use this page to link your account.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

GitHub Basics

GitHub Workflow

The following guides provide basic knowledge for understanding Git command usage and the workflow of GitHub.

Forking the Azure/azure-powershell repository

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. The following guide explains how to fork a GitHub repo.

Filing Issues

You can find all of the issues that have been filed for Azure PowerShell in the Issues section of this repository.

To file an issue, select one of the templates. This ensures that all of the necessary information is provided. The following are a few of the templates we provide:

You can find the code complete and release dates of the next three Azure PowerShell releases in the Milestones section of the Issues page. Each milestone will display the issues that are being worked on for the corresponding release.

Submitting Changes

Pull Requests

You can find all of the pull requests that have been opened in the Pull Requests section of this repository.

When creating a pull request, keep the following in mind:

  • Verify you are pointing to the fork and branch that your changes were made in.
  • Choose the correct branch you want your pull request to be merged into.
    • The main branch is for active development; changes in this branch will be in the next Azure PowerShell release.
    • The release-X.X.X branch is for active development during a release.
    • The preview branch is a snapshot of the last AzureRM release and should not be used for active development.
  • The pull request template that is provided must be filled out. Do not delete or ignore it when the pull request is created.
    • IMPORTANT: Deleting or ignoring the pull request template will delay the PR review process.
  • The SLA for reviewing pull requests is two business days.

Pull Request Guidelines

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.

The following set of guidelines must be adhered to when opening pull requests in the Azure PowerShell repository.

Target Release Types

Here are all types of releases of Azure PowerShell. Note that the type of release isn't necessarily aligned to the state of the swagger or service feature.

  • General release
    • This PR targets an official general release of Azure PowerShell.
    • Target version is x.y.z, no suffix.
      • Note: versions < 1.0.0 are also included in this category.
    • Target branch should be main or generation depending on the development approach.
  • Preview release
    • Public preview
      • This PR targets a preview release of Azure PowerShell. It is independent to the normal release cycle.
      • Target version is x.y.z-preview.
        • Note: if the major version is 0, it is considered a general release rather than preview.
      • Target branch should not be main nor generation. Please contact sprint master if you are unsure about which branch to target.
    • Private preview / Embargoed preview
      • This PR is related to some business secret. It should not be submitted to this repository. Contact sprint master for more details.
  • Engineering build
    • This PR does not require any kind of releases. It's for internal or private distribution.
    • Target branch should not be main nor generation. Please contact sprint master if you are unsure about which branch to target.

General guidelines

The following guidelines must be followed for every pull request that is opened.

  • Title of the pull request is clear and informative.
  • The appropriate ChangeLog.md file(s) has been updated:
    • For any service, the ChangeLog.md file can be found at src/{{SERVICE}}/{{SERVICE}}/ChangeLog.md.
    • A snippet outlining the change(s) made in the PR should be written under the ## Upcoming Release header -- no new version header should be added.
  • There are a small number of commits in your PR and each commit has an informative commit message.
  • All files shipped with a module should contain a proper Microsoft license header.
  • For public API changes to cmdlets:
    • A cmdlet design review has been approved for the changes in this repository. (Microsoft internal only).
    • The Markdown help files have been regenerated using the commands listed here.

For a comprehensive list of Azure PowerShell design guidelines and best practices, see Azure PowerShell Design Guidelines.

Testing guidelines

The following guidelines must be followed in every pull request that is opened.

  • Changes made have corresponding test coverage.
  • Tests should not include any hardcoded values, such as location, resource id, etc.
  • Tests should have proper setup of resources to ensure any user can re-record the test if necessary.
  • No existing tests should be skipped.

Cmdlet guidelines

Parameter guidelines

Piping guidelines

Module guidelines