From 87165aa5c5ce8d4136f6cdc1872214866a100574 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Sat, 15 Nov 2025 07:52:36 +0100 Subject: [PATCH 1/2] Add section on building and testing from source to README and CLA agreement --- CONTRIBUTING.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + 2 files changed, 118 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 107965376..8e69f53f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,6 +67,122 @@ To run the link-checker, follow these steps: `npm install -g markdown-link-check@3.8.5` * run `find . \*.md -exec markdown-link-check {} \;` +## Contributing to Code + +### Contributor License Agreement (CLA) + +To speed up the acceptance of any contribution to any DSC repositories, +you should sign the Microsoft [Contributor License Agreement (CLA)](https://cla.microsoft.com/) ahead of time. +If you've already contributed to DSC, PowerShell, or other Microsoft repositories in the past, congratulations! +You've already completed this step. +This is a one-time requirement for the DSC project. +Signing the CLA process is simple and can be done in less than a minute. +You don't have to do this up-front. +You can simply clone, fork, and submit your pull request as usual. +When your pull request is created, it is checked by the CLA bot. +If you have signed the CLA, the status check will be set to `passing`. +Otherwise, it will stay at `pending`. +Once you sign a CLA, all your existing and future pull requests will have the status check automatically set at `passing`. + +### Building and testing + +#### Prerequisites + +The DSC project is built using Rust and PowerShell. You need the following installed: + +* **PowerShell**: Version 7.2 or later +* **Rust**: Latest stable version (the build script can install/update Rust automatically) + +The build script (`build.new.ps1`) automatically installs or verifies other dependencies including +Clippy, Node.js, and tree-sitter. + +#### Quick start + +```powershell +# Build the project +./build.new.ps1 + +# Build with linting (recommended) +./build.new.ps1 -Clippy + +# Build and run all tests +./build.new.ps1 -Clippy -Test + +# Build in release mode (optimized) +./build.new.ps1 -Release +``` + +#### Running tests + +DSCv3 includes Rust unit tests and PowerShell Pester tests: + +```powershell +# Run all tests +./build.new.ps1 -Test + +# Run only Rust tests +./build.new.ps1 -Test -ExcludePesterTests + +# Run only Pester tests +./build.new.ps1 -Test -ExcludeRustTests + +# Run specific Pester test groups +./build.new.ps1 -SkipBuild -Test -ExcludeRustTests -PesterTestGroup dsc +``` + +Available Pester test groups: `dsc`, `adapters`, `extensions`, `resources`, `grammars` + +#### Cross-platform builds + +Build for specific architectures: + +```powershell +# Windows ARM +./build.new.ps1 -Architecture aarch64-pc-windows-msvc + +# macOS Apple Silicon +./build.new.ps1 -Architecture aarch64-apple-darwin + +# Linux x64 +./build.new.ps1 -Architecture x86_64-unknown-linux-gnu +``` + +#### Additional Information + +For detailed build instructions, troubleshooting, and CI/CD workflows, see the +[Build and Test Instructions](.github/instructions/instructions.md). + +### Pull Request Guidelines + +* Always create a pull request to the `main` branch of this repository. +* Avoid making big pull requests. Before you invest a large amount of time, file an issue and start a discussion with the community. +* Add a meaningful title to the PR describing what change you want to check in. +* When you create a pull request, include a summary about your changes in the PR description. + If the changes are related to an existing GitHub issue, please reference the issue in the PR description (e.g. `Fix #123`). +* Please use the present tense and imperative mood when describing your changes: + * Instead of "Adding support for new feature", write "Add support for new feature". + * Instead of "Fixed bug in parser", write "Fix bug in parser". +* If your change adds a new source file, ensure the appropriate copyright and license headers are on top: + * For `.rs` files use the copyright header with empty line after it: + + ```rust + // Copyright (c) Microsoft Corporation. + // Licensed under the MIT License. + + ``` + + * For `.ps1` and `.psm1` files use the copyright header with empty line after it: + + ```powershell + # Copyright (c) Microsoft Corporation. + # Licensed under the MIT License. + + ``` + +* Create and/or update tests when making code changes. +* Run tests and ensure they are passing before opening a pull request. +* All pull requests **must** pass CI checks before they can be merged. + ## Code of Conduct Enforcement Reports of abuse will be reviewed by the PS-Committee and if it has been determined that violations of the diff --git a/README.md b/README.md index a221ca2db..5f2d2ba82 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,8 @@ To install DSC v3: 1. Expand the release archive. 1. Add the folder containing the expanded archive contents to the `PATH`. +For information on building and testing DSC from source, see the [Contributing Guide](CONTRIBUTING.md). + ## Explore DSCv3 If you're new to DSC or configuration management, we recommend reviewing the [documentation][02]. From 4d92a684f4302d52bd1c3a90367cb4835ffd839d Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Mon, 17 Nov 2025 09:32:39 -0600 Subject: [PATCH 2/2] Apply suggestions from review --- CONTRIBUTING.md | 99 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 65 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8e69f53f1..5be3863db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,30 +71,48 @@ To run the link-checker, follow these steps: ### Contributor License Agreement (CLA) -To speed up the acceptance of any contribution to any DSC repositories, -you should sign the Microsoft [Contributor License Agreement (CLA)](https://cla.microsoft.com/) ahead of time. -If you've already contributed to DSC, PowerShell, or other Microsoft repositories in the past, congratulations! -You've already completed this step. -This is a one-time requirement for the DSC project. -Signing the CLA process is simple and can be done in less than a minute. -You don't have to do this up-front. -You can simply clone, fork, and submit your pull request as usual. -When your pull request is created, it is checked by the CLA bot. -If you have signed the CLA, the status check will be set to `passing`. -Otherwise, it will stay at `pending`. -Once you sign a CLA, all your existing and future pull requests will have the status check automatically set at `passing`. +Contributions to the DSC repository requires signing the [Contributor License Agreement (CLA)][01]. +You can manually sign the CLA at any time. When you submit a pull request to this repository, the +continuous integration will check whether you have already signed the CLA. If you haven't, the +automation will prompt you to do so as a comment on your PR. -### Building and testing +We can't accept any contributions without the author signing the CLA. Signing the CLA is a one-time +requirement and applies to contributions to Microsoft open source repositories. -#### Prerequisites +For more information, see [Contributor License Agreements][01]. -The DSC project is built using Rust and PowerShell. You need the following installed: +[01]: https://cla.microsoft.com/ + +### Building and testing -* **PowerShell**: Version 7.2 or later -* **Rust**: Latest stable version (the build script can install/update Rust automatically) +#### Prerequisites -The build script (`build.new.ps1`) automatically installs or verifies other dependencies including -Clippy, Node.js, and tree-sitter. +Building the DSC project requires PowerShell 7.2 or later to execute the build script. For more +information about installing PowerShell, see [Install PowerShell on Windows, Linux, and macOS][02]. + +DSC requires other tools for building the project. The build script (`build.new.ps1`) installs the +tools in the following table if they aren't already installed on your system: + +| Tool | Version | Platforms | Projects | +|:--------------------------------------------------------|:-------------:|:---------------------:|:-----------------------------------------------------| +| [Rust toolchain][03] | Latest stable | Linux, macOS, Windows | All Rust crates | +| [Visual Studio Build Tools for C++][04] | Latest stable | Windows | All Rust crates | +| [`cargo audit`][05] | Latest stable | Linux, macOS, Windows | All Rust crates | +| [Clippy][06] | Latest stable | Linux, macOS, Windows | All Rust crates | +| [Tree-sitter CLI][07] | Latest stable | Linux, macOS, Windows | All grammars | +| [NodeJS][08] | `v24` | Linux, macOS, Windows | All grammars | +| [**Pester** PowerShell module][09] | Latest stable | Linux, macOS, Windows | All acceptance tests | +| [**PSDesiredStateConfiguration** PowerShell module][10] | `v2.0.7` | Windows | `Microsoft.Windows/WindowsPowerShell` adapter tests | + +[02]: https://learn.microsoft.com/powershell/scripting/install/installing-powershell +[03]: https://rustup.rs/ +[04]: https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist +[05]: https://crates.io/crates/cargo-audit +[06]: https://doc.rust-lang.org/clippy/index.html +[07]: https://github.com/tree-sitter/tree-sitter/blob/master/crates/cli/README.md +[08]: https://nodejs.org/ +[09]: https://pester.dev/ +[10]: https://www.powershellgallery.com/packages/PSDesiredStateConfiguration/2.0.7 #### Quick start @@ -130,11 +148,18 @@ DSCv3 includes Rust unit tests and PowerShell Pester tests: ./build.new.ps1 -SkipBuild -Test -ExcludeRustTests -PesterTestGroup dsc ``` -Available Pester test groups: `dsc`, `adapters`, `extensions`, `resources`, `grammars` +Available Pester test groups include: + +- `dsc` - Acceptance tests for the `dsc` executable. +- `adapters` - Acceptance tests for projects in the `adapters` folder. +- `extensions` - Acceptance tests for projects in the `extensions` folder. +- `resources` - Acceptance tests for projects in the `resources` folder. +- `grammars` - Acceptance tests for projects in the `grammars` folder. #### Cross-platform builds -Build for specific architectures: +By default, the build script compiles code for the current platform and architecture. You can build +for other platforms and architectures with the `-Architecture` parameter: ```powershell # Windows ARM @@ -154,16 +179,22 @@ For detailed build instructions, troubleshooting, and CI/CD workflows, see the ### Pull Request Guidelines -* Always create a pull request to the `main` branch of this repository. -* Avoid making big pull requests. Before you invest a large amount of time, file an issue and start a discussion with the community. -* Add a meaningful title to the PR describing what change you want to check in. -* When you create a pull request, include a summary about your changes in the PR description. - If the changes are related to an existing GitHub issue, please reference the issue in the PR description (e.g. `Fix #123`). -* Please use the present tense and imperative mood when describing your changes: - * Instead of "Adding support for new feature", write "Add support for new feature". - * Instead of "Fixed bug in parser", write "Fix bug in parser". -* If your change adds a new source file, ensure the appropriate copyright and license headers are on top: - * For `.rs` files use the copyright header with empty line after it: +- Always create a pull request to the `main` branch of this repository. +- Avoid making big pull requests. Before you invest a large amount of time, file an issue and start + a discussion with the community. +- Add a meaningful title to the PR describing what change you want to check in. +- When you create a pull request, include a summary about your changes in the PR description. If + the changes are related to an existing GitHub issue, please reference the issue in the PR + description (e.g. `Fix #123`). +- Please use the present tense and imperative mood when describing your changes: + + - Instead of `Adding support for new feature`, write `Add support for new feature`. + - Instead of `Fixed bug in parser`, write `Fix bug in parser`. + +- If your change adds a new source file, ensure the appropriate copyright and license headers are + included at the top of the file: + + - For `.rs` files, use the copyright header with an empty line after it: ```rust // Copyright (c) Microsoft Corporation. @@ -171,7 +202,7 @@ For detailed build instructions, troubleshooting, and CI/CD workflows, see the ``` - * For `.ps1` and `.psm1` files use the copyright header with empty line after it: + - For `.ps1` and `.psm1` files, use the copyright header with an empty line after it: ```powershell # Copyright (c) Microsoft Corporation. @@ -179,8 +210,8 @@ For detailed build instructions, troubleshooting, and CI/CD workflows, see the ``` -* Create and/or update tests when making code changes. -* Run tests and ensure they are passing before opening a pull request. +* Create and update relevant tests when making code changes. +* Run tests and ensure they're passing before opening a pull request. * All pull requests **must** pass CI checks before they can be merged. ## Code of Conduct Enforcement