diff --git a/docs/concepts/baselines.md b/docs/concepts/baselines.md index 2614295cbf..4744cb1faa 100644 --- a/docs/concepts/baselines.md +++ b/docs/concepts/baselines.md @@ -29,7 +29,7 @@ A baseline groups are set by configuring the [Baseline.Group][2] option. !!! Experimental _Baseline groups_ are a work in progress and subject to change. Currently, _baseline groups_ allow only a single baseline to be referenced. - [Join or start a disucssion][3] to let us know how we can improve this feature going forward. + [Join or start a discussion][3] to let us know how we can improve this feature going forward. !!! Tip You can use baseline groups to reference a baseline. diff --git a/docs/concepts/cli/index.md b/docs/concepts/cli/index.md index 8e3dbd1d02..e47b5f06c1 100644 --- a/docs/concepts/cli/index.md +++ b/docs/concepts/cli/index.md @@ -4,25 +4,18 @@ PSRule provides a command-line interface (CLI) to run rules and analyze results. This article describes the commands available in the CLI. + For details on installing the PSRule CLI, see [Install PSRule](../../install.md#with-cli). + ## Commands -The following commands are available in the PSRule CLI: +The following commands are available in the CLI: - [run](./run.md) — Run rules against an input path and output the results. - [module](./module.md) — Manage or restore modules tracked by the module lock file and configured options. -## Global options - -The following options are available in the PSRule CLI: - -### `--option` - -Specifies the path to an options file. -By default, the CLI will look for a file named `ps-rule.yaml` in the current directory. - -### `--version` +## `--version` -Show the version information for the PSRule CLI. +Show the version information for PSRule. For example: @@ -30,7 +23,16 @@ For example: ps-rule --version ``` -### `--help` +## Global options + +The following global options can be used with any command: + +### `--option` + +Specifies the path to an options file. +By default, the CLI will look for a file named `ps-rule.yaml` in the current directory. + +### `-?` | `-h` | `--help` Display help and usage information for the PSRule CLI and commands. To display help for a specific command, use `--help` with the command name. diff --git a/docs/concepts/cli/module.md b/docs/concepts/cli/module.md index 295933dbda..337a718436 100644 --- a/docs/concepts/cli/module.md +++ b/docs/concepts/cli/module.md @@ -1,3 +1,7 @@ +--- +title: ps-rule module command +--- + # ps-rule module !!! Abstract @@ -5,6 +9,12 @@ The module lock file, provides consistent module versions across multiple machines and environments. For more information, see [Lock file](../lockfile.md). +## Usage + +```bash title="PSRule CLI command-line" +ps-rule module [subcommand] [options] +``` + To use the `module` command, choose one of the available subcommands: - [module init](#module-init) diff --git a/docs/concepts/cli/run.md b/docs/concepts/cli/run.md index 81004625c5..6a4856a9bf 100644 --- a/docs/concepts/cli/run.md +++ b/docs/concepts/cli/run.md @@ -1,9 +1,19 @@ +--- +title: ps-rule run command +--- + # ps-rule run !!! Abstract Use the `run` command to run rules against an input path and output the results. -## Optional parameters +## Usage + +```bash title="PSRule CLI command-line" +ps-rule run [options] +``` + +## Options ### `--input-path` | `-f` diff --git a/docs/creating-your-pipeline.md b/docs/creating-your-pipeline.md index 6d56fcfbe6..6cea3b61ba 100644 --- a/docs/creating-your-pipeline.md +++ b/docs/creating-your-pipeline.md @@ -204,7 +204,7 @@ To only process files that have changed within a pull request, set the `Input.Ig ``` !!! Tip - In some cases it may be nessessary to set `Repository.BaseRef` to the default branch of your repository. + In some cases it may be necessary to set `Repository.BaseRef` to the default branch of your repository. By default, PSRule will detect the default branch of the repository from the build system environment variables. [8]: concepts/PSRule/en-US/about_PSRule_Options.md#inputignoreunchangedpath diff --git a/docs/expressions/functions.md b/docs/expressions/functions.md index 0ece90cbb8..3000999097 100644 --- a/docs/expressions/functions.md +++ b/docs/expressions/functions.md @@ -1,14 +1,14 @@ # Functions !!! Abstract - _Functions_ are an advanced lanaguage feature specific to YAML and JSON expressions. + _Functions_ are an advanced language feature specific to YAML and JSON expressions. That extend the language to allow for more complex use cases with expressions. Functions don't apply to script expressions because PowerShell already has rich support for complex manipulation. !!! Experimental _Functions_ are a work in progress and subject to change. We hope to add more functions, broader support, and more detailed documentation in the future. - [Join or start a disucssion][1] to let us know how we can improve this feature going forward. + [Join or start a discussion][1] to let us know how we can improve this feature going forward. [1]: https://github.com/microsoft/PSRule/discussions diff --git a/docs/expressions/sub-selectors.md b/docs/expressions/sub-selectors.md index 57cea7450b..1c9e1263cf 100644 --- a/docs/expressions/sub-selectors.md +++ b/docs/expressions/sub-selectors.md @@ -8,7 +8,7 @@ !!! Experimental _Sub-selectors_ are a work in progress and subject to change. We hope to add broader support, and more detailed documentation in the future. - [Join or start a disucssion][1] to let us know how we can improve this feature going forward. + [Join or start a discussion][1] to let us know how we can improve this feature going forward. [1]: https://github.com/microsoft/PSRule/discussions diff --git a/docs/faq.md b/docs/faq.md index 5f72d83f66..3198a13e09 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -174,7 +174,7 @@ input: ## How do I disable or suppress the not processed warning? -You may recieve a warning message suggesting a file or object _has not been processed_. +You may receive a warning message suggesting a file or object _has not been processed_. If there are no rules that apply to the file or object this warning will be displayed. !!! Note @@ -232,12 +232,12 @@ Alternatively, you can provide your own reasons to complement standard PowerShel ## Collection of telemetry -PSRule and PSRule for Azure currently do not collect any telemetry during installation or execution. +PSRule currently does not collect any telemetry during installation or execution. -PowerShell (used by PSRule for Azure) does collect basic telemetry by default. +PowerShell (used by PSRule) does collect basic telemetry by default. Collection of telemetry in PowerShell and how to opt-out is explained in [about_Telemetry][11]. - [11]: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_telemetry + [11]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_telemetry *[IaC]: Infrastructure as Code *[CI]: Continuous Integration diff --git a/docs/features.md b/docs/features.md index a55cd012aa..39c9cab92e 100644 --- a/docs/features.md +++ b/docs/features.md @@ -17,8 +17,8 @@ PSRule allows you to quickly plug-in Infrastructure as Code (IaC) controls into Run on MacOS, Linux, and Windows or anywhere PowerShell is supported. Native support for popular continuous integration (CI) systems includes: -- **GitHub Actions** - Trigger tests for GitHub repositories using workflows. -- **Azure Pipelines** - Use tasks to run tests in Azure DevOps YAML or Classic pipelines and releases. +- **GitHub Actions** — Trigger tests for GitHub repositories using workflows. +- **Azure Pipelines** — Use tasks to run tests in Azure DevOps YAML or Classic pipelines and releases. ## Extensible @@ -27,7 +27,7 @@ Regardless of the format you choose, any combination of YAML, JSON, or PowerShel - **YAML** — Use a popular, easy to read, and learn IaC format. With YAML, you can quickly build out common rules with minimal effort and no scripting experience. -- **JSON** — Is ubiquitous used by many tools. +- **JSON** — Is ubiquitous, used by many tools. While this format is typically harder to read then YAML it is easy to automate. You may prefer to use this format if you are generating rules with automation. - **PowerShell** — Is a flexible scripting language. @@ -54,8 +54,8 @@ The following built-in features improve portability: - [Suppression][4] — Allows you to handle and keep exceptions auditable in git history. - **Approval** — Use [code owners][6] and [branch policy][7] concepts to control changes. - [Documentation][5] — Provide guidance on how to resolve detected issues. - - **Quick** - Use a one liner to quickly add a hint or reference on rules you build. - - **Detailed** - Support for markdown allows you to provide detailed detailed guidance to resolve issues. + - **Quick** — Use a one liner to quickly add a hint or reference on rules you build. + - **Detailed** — Support for markdown allows you to provide detailed detailed guidance to resolve issues. [1]: authoring/packaging-rules.md [2]: concepts/PSRule/en-US/about_PSRule_Options.md diff --git a/docs/install.md b/docs/install.md index 8c15f8c496..5f82904e36 100644 --- a/docs/install.md +++ b/docs/install.md @@ -2,16 +2,16 @@ author: BernieWhite --- -# Install PSRule tools +# Install PSRule PSRule supports running within continuous integration (CI) systems or locally. It is shipped as a PowerShell module which makes it easy to install and distribute updates. Task | Options ---- | ------ -Run tests within CI pipelines | With [GitHub Actions][8] _or_ [Azure Pipelines][9] _or_ [PowerShell][10] -Run tests locally during development | With [Visual Studio Code][11] _and_ [PowerShell][10] -Create custom tests for your organization | With [Visual Studio Code][11] _and_ [PowerShell][10] +Run tests within CI pipelines | With [GitHub Actions][8] _or_ [Azure Pipelines][9] _or_ [CLI][13] _or_ [PowerShell][10] +Run tests locally during development | With [Visual Studio Code][11] _and_ [CLI][13] / [PowerShell][10] +Create custom tests for your organization | With [Visual Studio Code][11] _and_ [CLI][13] / [PowerShell][10] !!! Tip PSRule provides native integration to popular CI systems such as GitHub Actions and Azure Pipelines. @@ -22,6 +22,7 @@ Create custom tests for your organization | With [Visual Studio Code][11] _and_ [9]: #with-azure-pipelines [10]: #with-powershell [11]: #with-visual-studio-code + [13]: #with-cli ## With GitHub Actions @@ -108,20 +109,29 @@ The Visual Studio Code extension includes a built-in tasks and configuration sch ## With CLI -PSRule can be installed from the .NET CLI using the following command line: +PSRule can be installed from NuGet.org using the .NET CLI where the .NET 8.0 SDK is available. +You can use this option to install on CI workers that are not natively supported. + +To install PSRule as a global tool use the following command line: ```bash dotnet tool install -g Microsoft.PSRule.Tool ``` -For a list of commands you can use with the PSRule CLI, see [PSRule CLI][cli]. +To install a specific version use the following command line: + +```bash +dotnet tool install -g Microsoft.PSRule.Tool --version 3.0.0-B0151 +``` + +For a list of commands supported by the CLI, see [PSRule CLI][cli]. [cli]: concepts/cli/index.md ## With PowerShell PSRule can be installed locally from the PowerShell Gallery using PowerShell. -You can also use this option to install on CI workers that are not natively supported. +You can use this option to install on CI workers that are not natively supported. ### Prerequisites diff --git a/docs/license-contributing.md b/docs/license-contributing.md index c7fb58f3ca..29322af772 100755 --- a/docs/license-contributing.md +++ b/docs/license-contributing.md @@ -15,7 +15,7 @@ In addition to our team, we hope you will think about contributing too. Here is how you can get started: - :octicons-bug-16: Report issues. -- :octicons-thumbsup-16: Upvote existing issues that are important to you. +- :octicons-thumbsup-16: Up-vote existing issues that are important to you. - :octicons-book-16: Improve documentation. - :octicons-git-pull-request-16: Contribute code. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 3d1c8975ee..524c0b437c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -74,7 +74,7 @@ When running PSRule you may encounter an error similar to the following: This error typically indicates a problem with the YAML syntax in the `ps-rule.yaml` file. Double check the file for incorrect indentation or missing punctuation such as `-` and `:` characters. -If you still have an issue, try resaving the file as UTF-8 in an editor such as Visual Studio Code. +If you still have an issue, try re-saving the file as UTF-8 in an editor such as Visual Studio Code. ## PSR0002 - Summary results are not supported with Job Summaries diff --git a/docs/validating-locally.md b/docs/validating-locally.md index f564b5ee3f..ec379b7d75 100644 --- a/docs/validating-locally.md +++ b/docs/validating-locally.md @@ -10,7 +10,7 @@ This allows you to test Infrastructure as Code (IaC) artifacts before pushing ch !!! Tip If you haven't already, follow the instructions on [installing locally][1] before continuing. - [1]: install-instructions.md#installing-locally + [1]: install.md#with-powershell ## With Visual Studio Code diff --git a/docs/versioning.md b/docs/versioning.md index a42f03e4d5..60e3a5246e 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -24,11 +24,11 @@ Module versions and change log details for pre-releases will be removed as stabl ## Experimental features -From time to time we may ship experimential features. -These features are generally marked experimential in the change log as these features ship. +From time to time we may ship experiential features. +These features are generally marked experiential in the change log as these features ship. Experimental features may ship in stable releases, however to use them you may need to: -- Enable or explictly reference them. +- Enable or explicitly reference them. !!! Important Experimental features should be considered work in progress. diff --git a/src/PSRule.BuildTask/Generators/EngineVersionGenerator.cs b/src/PSRule.BuildTask/Generators/EngineVersionGenerator.cs index f217d3f46e..c46b5abfa4 100644 --- a/src/PSRule.BuildTask/Generators/EngineVersionGenerator.cs +++ b/src/PSRule.BuildTask/Generators/EngineVersionGenerator.cs @@ -6,7 +6,7 @@ namespace PSRule.BuildTask.Generators; /// -/// Generator contants for PSRule engine version. +/// Generator constants for PSRule engine version. /// [Generator] public sealed class EngineVersionGenerator : ISourceGenerator