Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
164 lines (114 loc) · 7.92 KB

CONTRIBUTING.md

File metadata and controls

164 lines (114 loc) · 7.92 KB

Contributing to Microsoft Entra PowerShell

This repository contains PowerShell cmdlets for developers and administrators to develop, deploy, administer, and manage Microsoft Entra product family 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 Microsoft Graph organization. Use this page to link your account.

Code of Conduct

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

GitHub Basics

GitHub Workflow

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

Getting the code

There are two ways to contribute code changes:

Option 1: Clone directly (recommended for regular contributors)

Clone the repository directly and create a feature branch. Pull requests created from branches pushed directly to the repository will have the CI/CD pipeline run automatically.

git clone https://github.com/microsoftgraph/entra-powershell.git
cd entra-powershell
git checkout -b feature/your-change-description

Option 2: Fork the repository

External contributors can fork the repository and submit pull requests from their fork. Note that pull requests from forks will not trigger the CI/CD pipeline automatically — an internal reviewer must manually trigger the pipeline run after reviewing the changes.

# Fork via GitHub UI, then clone your fork
git clone https://github.com/<YOUR-USERNAME>/entra-powershell.git
cd entra-powershell
git remote add upstream https://github.com/microsoftgraph/entra-powershell.git
git checkout -b feature/your-change-description

Note: Regardless of which option you choose, ensure all tests pass locally before submitting your PR. For fork-based PRs, the pipeline will be triggered by an internal reviewer once the changes are reviewed.

Filing Issues

You can find all of the issues filed for Microsoft Entra PowerShell in the Issues section of this repository.

To file an issue, select one of the templates. The template 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 upcoming Entra PowerShell releases in the Milestones section of the Issues page. Each milestone displays the issues that are being worked on for the corresponding release.

Submitting Changes

Pull Requests

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

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

  • Verify you're pointing to the 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 Entra PowerShell release.
  • The pull request template that is provided must be filled out. Don't delete or ignore it when the pull request is created.
    • IMPORTANT: Deleting or ignoring the pull request template delays the PR review process.
  • Once your PR is complete and ready for review, add the Ready For Review label to signal the team.
  • The SLA for reviewing pull requests is three business days.

Pull Request Guidelines

A pull request template will automatically be included as a part of your PR. Fill out the checklist as specified. Pull requests will not be reviewed unless they include a properly completed checklist.

Testing guidelines

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

  • Changes made have corresponding test coverage.
  • Tests shouldn't include any hardcoded values, such as DisplayName, resource ID, etc.
  • No existing tests should be skipped.
  • All API calls in tests must be mocked — never call the real Microsoft Graph API in unit tests.
  • Tests must pass both locally and in CI before a PR is reviewed.

For detailed instructions on writing and running tests, see the Testing Guide.

Building and testing locally

Before submitting a PR, build and validate your changes locally:

  1. Build the module — see the Local Build and Validation Guide or BUILD.md.
  2. Run unit tests — use Pester to run all tests and ensure zero failures.
  3. Run static analysis — use PSScriptAnalyzer on your changed files.
# Quick validation workflow
.\build\Install-Dependencies.ps1 -ModuleName Entra
. .\build\Common-functions.ps1
Create-ModuleHelp -Module Entra
.\build\Create-EntraModule.ps1 -Module 'Entra'
.\build\Create-EntraModule.ps1 -Module 'Entra' -Root
Import-Module .\bin\Microsoft.Entra.psd1 -Force

# Run tests
Invoke-Pester -Path .\test\Entra\ -Output Detailed

# Static analysis
Invoke-ScriptAnalyzer -Path .\module\Entra\ -Recurse -Severity Warning

For the full guide, including safe testing practices and troubleshooting, see the Local Build and Validation Guide.

Microsoft Entra PowerShell documentation contributions

The official Microsoft Entra PowerShell documentation is available on learn.microsoft.com.

We welcome public contributions to the Microsoft Entra PowerShell documentation. There are two types of documentation for Microsoft Entra PowerShell, each with a different workflow:

  • Conceptual Documentation: To submit changes for content in the conceptual directory, make a pull request against the public docs repository. See more details, Contributing guide.
  • Reference Documentation: To submit changes for command-line help and online documentation for both beta and v1.0 versions of the module, make a pull request against microsoftgraph/entra-powershell. Updates are pushed to learn.microsoft.com every two weeks.

Note: The Microsoft Entra PowerShell module reference documentation generates both the command-line help and public cmdlet references with the single source of truth being the microsoftgraph/entra-powershell.