Skip to content

Get started contributing#

Welcome to PSRule for Azure! We are excited to have you contribute to the project. This guide will walk you through the process of setting up your local development environment, understanding the project structure, and submitting your first contribution.

Fork and clone the repository#

To start contributing, the first step is to fork the repository to your GitHub account and then clone it to your local machine.

  1. Fork the repository — Fork.
  2. Clone your fork — Once the repository is forked, clone it to your local machine.
Git
git clone https://github.com/YOUR_USERNAME/PSRule.Rules.Azure.git
cd PSRule.Rules.Azure

Set up your local development environment#

PSRule for Azure requires the following dependencies for development:

  • .NET SDK 8.0 — is used for building the project and core features.
  • PowerShell — is used for building the project, running the rules tests, and development of some rules.
  • Az PowerShell module — is used for exporting Azure resources and policies (in-flight).

To install development dependencies, refer to the installation guide.

Understand the Project Structure#

Before you start coding, it's helpful to understand the organization of the repository. Some of the most common sub-directories that are worth knowing about include:

Contributing to Code#

Before writing a fix or feature enhancement, ensure that an issue is logged. Be prepared to discuss your feature and take feedback. Additionally, ensure that your changes include unit tests and any necessary updates to the documentation.

  1. Create a new branch from main in your fork for your changes.
  2. Add commits in your branch, making sure they are logically grouped and well-described.
  3. If you have updated module code or rules, also update the docs/CHANGELOG-v1.md.
    • Note: You don't need to update the docs/CHANGELOG-v1.md for changes to unit tests or documentation.
  4. Build your changes locally before pushing them. This ensures that they work as expected.
  5. Create a Pull Request (PR):
    • Once you are ready for your changes to be reviewed, create a PR to merge changes into the main branch.
    • If your changes are not ready for review, create a draft pull request instead.
  6. The Continuous Integration (CI) process will automatically build your changes. Ensure that your changes build successfully to be merged.
    • If there are build errors, push new commits to your branch to fix them.

Building and testing your changes#

Before opening a pull request, it’s important to build and test your changes locally. PSRule for Azure uses Continuous Integration (CI) pipelines to test changes across MacOS, Linux, and Windows configurations.

  1. Build and test locally — Ensure that you can build your changes locally. Follow the instructions in the Building from Source guide to set up your local environment for testing.
  2. Run all tests — Before creating your PR, run the tests to make sure your changes are working as expected.
PowerShell
Invoke-Build Test -AssertStyle Client

Example Unit Test#

Here is an example of a unit test for validating rules: Azure.ACR.Tests.ps1 Example

Commit your changes#

Once your changes are ready, commit your changes to your fork:

Git
git add .
git commit -m "Brief description of your changes"
git push origin YOUR_BRANCH

Submit a pull request (PR)#

  • Go to your forked repository on GitHub.
  • Click on "Compare & pull request."
  • In the provided PR template provide a clear and concise description of your changes.

Review and approval#

What you can expect from review and approval of your contribution:

  • Once your PR is submitted — project maintainers will review your changes and make suggestions or comments. Be prepared to make updates based on feedback until your PR is approved. If you are unclear on the feedback you can comment in the PR to get clarification.
  • Automated CI tests — for your PR do not run automatically, a maintainer must approve running the workflow. Once approved, if any automated CI tests fail be prepared to test your changes locally and update your branch. If you get stuck, you can comment in the PR to ask questions.
  • Update your PR — by adding commits to your branch and pushing changes to GitHub. After a few moments your PR will update with your latest changes. Avoid using forced pushes or squashing changes while your PR is active, as this makes it harder to review your changes.
  • Contributor License Agreement (CLA) — The Microsoft policy bot may request you accept the CLA. Please read and follow the instructions of the bot to complete acceptance of the Microsoft CLA. We can not approve and merge your PR if it is flagged by the bot until the CLA is accepted.
  • After PR approval — your PR will be merged into the main repository by the maintainers.

Stay engaged#

  • Follow discussions and updates by subscribing to issues and PRs.
  • Keep up with the latest changes in the project by regularly pulling updates from the upstream repository.
  • Share feedback and help others when possible.

Further resources#

Comments