diff --git a/docs/license-contributing/first-contributors-guide.md b/docs/license-contributing/first-contributors-guide.md new file mode 100644 index 00000000000..87840e64bcb --- /dev/null +++ b/docs/license-contributing/first-contributors-guide.md @@ -0,0 +1,127 @@ +# 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** — [:octicons-repo-forked-24: Fork][1]. +2. **Clone your fork** — Once the repository is forked, clone it to your local machine. + +```bash title="Git" +git clone https://github.com/YOUR_USERNAME/PSRule.Rules.Azure.git +cd PSRule.Rules.Azure +``` + + [1]: https://github.com/Azure/PSRule.Rules.Azure/fork + +## 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][2]. + + [2]: https://azure.github.io/PSRule.Rules.Azure/install/#development-dependencies + +## 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: + +- [docs/](https://github.com/Azure/PSRule.Rules.Azure/tree/main/docs) — All documentation lives written in markdown. + - [en/rules/](https://github.com/Azure/PSRule.Rules.Azure/tree/main/docs/en/rules) — Markdown files for each rule. + - [CHANGELOG-v1.md](https://github.com/Azure/PSRule.Rules.Azure/blob/main/docs/CHANGELOG-v1.md) — Change log. +- [samples/](https://github.com/Azure/PSRule.Rules.Azure/tree/main/samples) — Community samples. +- [src/PSRule.Rules.Azure/](https://github.com/Azure/PSRule.Rules.Azure/tree/main/src/PSRule.Rules.Azure) — Module source code. + - [rules/](https://github.com/Azure/PSRule.Rules.Azure/tree/main/src/PSRule.Rules.Azure/rules) — Rule source code. +- [tests/PSRule.Rules.Azure.Tests/](https://github.com/Azure/PSRule.Rules.Azure/tree/main/tests/PSRule.Rules.Azure.Tests) — Tests for rules and modules features. + +## 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][3] 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 title="PowerShell" +Invoke-Build Test -AssertStyle Client +``` + + [3]: https://azure.github.io/PSRule.Rules.Azure/install/#building-from-source + +### Example Unit Test + +Here is an example of a unit test for validating rules: +[Azure.ACR.Tests.ps1 Example](https://github.com/Azure/psrule.rules.azure/blob/main/tests/PSRule.Rules.Azure.Tests/Azure.ACR.Tests.ps1#L40-L56) + +## Commit your changes + +Once your changes are ready, commit your changes to your fork: + +```bash title="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 + +- [Contributing Guide](https://github.com/Azure/PSRule.Rules.Azure/blob/main/CONTRIBUTING.md) – Detailed guidelines for contributing to the project. +- [PSRule Documentation](https://github.com/microsoft/PSRule) – Learn about the PSRule engine used in this project. +- [Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/) – Understand the principles that guide this project. diff --git a/mkdocs.yml b/mkdocs.yml index 00cc1a28d5f..3df816cf0e3 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -75,6 +75,7 @@ nav: - Samples: samples.md - License and contributing: - Index: license-contributing/index.md + - Get started contributing: license-contributing/first-contributors-guide.md - Writing documentation: license-contributing/writing-documentation.md - Past hackathons: license-contributing/hackathons.md - Related projects: related-projects.md