From 61544e9a27bf63d7fa965dd86172888907f83070 Mon Sep 17 00:00:00 2001 From: Bernie White Date: Thu, 28 Nov 2024 14:59:41 +1000 Subject: [PATCH] Update packaging for V2 --- .vscode/settings.json | 3 +- .vscodeignore | 1 + CHANGELOG.md | 7 ++ README.md | 8 ++- extension.md | 157 ++++++++++++++++++++++++++++++++++++++++++ package.json | 6 +- 6 files changed, 176 insertions(+), 6 deletions(-) create mode 100644 extension.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 0d153abd..a4863e35 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -42,6 +42,7 @@ "pwsh" ], "git.branchProtection": [ - "main" + "main", + "release/*" ] } diff --git a/.vscodeignore b/.vscodeignore index 1fcacf80..3caf4875 100644 --- a/.vscodeignore +++ b/.vscodeignore @@ -22,3 +22,4 @@ SECURITY.md SUPPORT.md .markdownlint.json out/updates.txt +README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index aaa9b06d..b4ccf7d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,13 @@ Continue reading to see the changes included in the latest version. ## Unreleased +## v2.9.1 + +What's changed since v2.9.0: + +- Engineering: + - Updated display name to clearly indicate this extension is V2 in the marketplace by @BernieWhite. + ## v2.9.0 What's changed since v2.8.0: diff --git a/README.md b/README.md index 86650d6b..87303106 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,12 @@ Validate infrastructure as code (IaC) and DevOps repositories using the PSRule PowerShell module. PSRule is powerful, feature rich, and highly customizable to meet your needs. -![module-version-badge] +> [!NOTE] +> This extension is being migrated into . +> Currently this repository reflects the last stable release of v2.9.x. +> An improve PSRule extension for V3 will be release from the new repository. +> Please log an new issues at +--- This extension is available in two release channels: @@ -151,7 +156,6 @@ This project is [licensed under the MIT License][license]. [ext-stable]: https://marketplace.visualstudio.com/items?itemName=bewhite.psrule-vscode [ext-stable-version-badge]: https://vsmarketplacebadges.dev/version/bewhite.psrule-vscode.png [ext-stable-installs-badge]: https://vsmarketplacebadges.dev/installs-short/bewhite.psrule-vscode.png -[module-version-badge]: https://img.shields.io/powershellgallery/v/PSRule.png?label=PowerShell%20Gallery&color=brightgreen [contribution guide]: https://github.com/Microsoft/PSRule-vscode/blob/main/CONTRIBUTING.md [license]: https://github.com/Microsoft/PSRule-vscode/blob/main/LICENSE [ps-rule.yaml]: https://aka.ms/ps-rule/options diff --git a/extension.md b/extension.md new file mode 100644 index 00000000..86650d6b --- /dev/null +++ b/extension.md @@ -0,0 +1,157 @@ +# PSRule + +Validate infrastructure as code (IaC) and DevOps repositories using the PSRule PowerShell module. +PSRule is powerful, feature rich, and highly customizable to meet your needs. + +![module-version-badge] + +This extension is available in two release channels: + +Channel | Description | Version/ downloads +------- | ----------- | --- +[Preview][ext-preview] | More frequent releases but more likely to contain bugs. | [![Preview][ext-preview-version-badge]][ext-preview] ![ext-preview-installs-badge] +[Stable][ext-stable] | Less frequent releases, with more user testing, experimental features are disabled. | [![Stable][ext-stable-version-badge]][ext-stable] ![ext-stable-installs-badge] + +## Features + +### CodeLens + +

+ CodeLens showing link to create documentation +

+ +- CodeLens shows links to create or edit markdown documentation from rules in YAML, JSON, or PowerShell. + - **Open documentation** — Opens rule markdown documentation in the editor. + - The location for storing documentation is configurable in the extension settings. + - By default, a locale specific folder is created in the same directory as the rule file. + - **Create documentation** — Creates a new markdown file for the rule based on a snippet. + - New markdown documentation is created with the built-in _Rule Doc_ snippet. + - An alternative snippet can be specified by configuring extension settings. + +### IntelliSense + +

+ Options suggestion context menu +

+ +- Adds IntelliSense and validation support for configuring options and resources. + - **Workspace options** — use IntelliSense to configure options for the workspace. + - Type or trigger IntelliSense with `Ctrl+Space` from `ps-rule.yaml`. + - **Create resources** — define _baselines_ and _selectors_ by using pre-built snippets and IntelliSense. + +

+ Rule definition snippet +

+ +- Adds snippets for defining new rules. + - **Define rules** with snippets and IntelliSense support. + - Trigger IntelliSense by typing `rule` in a `.Rule.ps1`, `.Rule.yaml`, or `.Rule.jsonc` file. + IntelliSense can also be triggered by using the shortcut `Ctrl+Space`. + +

+ Rule markdown documentation snippet +

+ +- Adds snippets for creating markdown documentation. + - **Quick documentation** — create rule documentation to provide rule recommendations and examples. + - Trigger IntelliSense by typing `rule` in a `.md` file. + IntelliSense can also be triggered by using the shortcut `Ctrl+Space`. + +### Quick tasks + +

+ Built-in tasks shown in task list +

+ +- Adds quick tasks for analysis directly from Visual Studio Code. + - **Run analysis** — runs rules against files in the current workspace. + - _Input path_, _Baseline_, _Modules_, and _Outcome_ options can be configured per task. + - _Output as_, and showing a _Not processed warning_ options can be configured by workspace or user. + - Rule stored in `.ps-rule/` are automatically used by default. + - Use the built-in analysis task by running or configuring the task from the _Terminal_ menu. + +## Configuration + +In addition to configuring the [ps-rule.yaml] options file, the following settings are available. + +Name | Description +---- | ----------- +`PSRule.codeLens.ruleDocumentationLinks` | Enables Code Lens that displays links to rule documentation. This is an experimental feature that requires experimental features to be enabled. +`PSRule.documentation.path` | The path to look for rule documentation. When not set, the path containing rules will be used. +`PSRule.documentation.localePath` | The locale path to use for locating rule documentation. The VS Code locale will be used by default. +`PSRule.documentation.customSnippetPath` | The path to a file containing a rule documentation snippet. When not set, built-in PSRule snippets will be used. +`PSRule.documentation.snippet` | The name of a snippet to use when creating new rule documentation. By default, the built-in `Rule Doc` snippet will be used. +`PSRule.execution.notProcessedWarning` | Warn when objects are not processed by any rule. This option is deprecated and replaced by `PSRule.execution.unprocessedObject`. +`PSRule.execution.ruleExcluded` | Determines how to handle excluded rules. When set to `None`, PSRule will use the default (`Ignore`), unless set by PSRule options. +`PSRule.execution.ruleSuppressed` | Determines how to handle suppressed rules. When set to `None`, PSRule will use the default (`Warn`), unless set by PSRule options. +`PSRule.execution.unprocessedObject` | Determines how to report objects that are not processed by any rule. When set to `None`, PSRule will use the default (`Warn`), unless set by PSRule options. +`PSRule.experimental.enabled` | Enables experimental features in the PSRule extension. +`PSRule.notifications.showChannelUpgrade` | Determines if a notification to switch to the stable channel is shown on start up. +`PSRule.notifications.showPowerShellExtension` | Determines if a notification to install the PowerShell extension is shown on start up. +`PSRule.output.as` | Configures the output of analysis tasks, either summary or detailed. +`PSRule.rule.baseline` | The name of the default baseline to use for executing rules. This setting can be overridden on individual PSRule tasks. + +## Support + +This project uses GitHub Issues to track bugs and feature requests. +Please search the existing issues before filing new issues to avoid duplicates. + +- For new issues, file your bug or feature request as a new [issue]. +- For help, discussion, and support questions about using this project, join or start a [discussion]. + +Support for this project/ product is limited to the resources listed above. + +## Installing PSRule module + +PSRule is available from the PowerShell Gallery and is required for this extension to work. + +To install the module use the following command from a PowerShell prompt. + +```powershell +Install-Module -Name PSRule -Scope CurrentUser; +``` + +## Installing the extension + +You can install the latest release of the extension by following the steps in the [Visual Studio Code documentation][vscode-ext-gallery]. +In the Extensions pane, search for _PSRule_ extension and install it there. +You will get notified automatically about any future extension updates. + +```text +code --install-extension bewhite.psrule-vscode-preview +``` + +> NOTE: If you are using VS Code Insiders, the command will be `code-insiders`. + +## Contributing + +This project welcomes contributions and suggestions. +If you are ready to contribute, please visit the [contribution guide]. + +## Code of Conduct + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) +or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +## Maintainers + +- [Bernie White](https://github.com/BernieWhite) + +## License + +This project is [licensed under the MIT License][license]. + +[issue]: https://github.com/Microsoft/PSRule-vscode/issues +[discussion]: https://github.com/microsoft/PSRule-vscode/discussions +[vscode-ext-gallery]: https://code.visualstudio.com/docs/editor/extension-gallery +[ext-preview]: https://marketplace.visualstudio.com/items?itemName=bewhite.psrule-vscode-preview +[ext-preview-version-badge]: https://vsmarketplacebadges.dev/version/bewhite.psrule-vscode-preview.png +[ext-preview-installs-badge]: https://vsmarketplacebadges.dev/installs-short/bewhite.psrule-vscode-preview.png +[ext-stable]: https://marketplace.visualstudio.com/items?itemName=bewhite.psrule-vscode +[ext-stable-version-badge]: https://vsmarketplacebadges.dev/version/bewhite.psrule-vscode.png +[ext-stable-installs-badge]: https://vsmarketplacebadges.dev/installs-short/bewhite.psrule-vscode.png +[module-version-badge]: https://img.shields.io/powershellgallery/v/PSRule.png?label=PowerShell%20Gallery&color=brightgreen +[contribution guide]: https://github.com/Microsoft/PSRule-vscode/blob/main/CONTRIBUTING.md +[license]: https://github.com/Microsoft/PSRule-vscode/blob/main/LICENSE +[ps-rule.yaml]: https://aka.ms/ps-rule/options diff --git a/package.json b/package.json index 51eb926c..a3424003 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "vscode": "^1.78.0" }, "license": "SEE LICENSE IN LICENSE", - "homepage": "https://github.com/microsoft/PSRule-vscode/blob/main/README.md", + "homepage": "https://github.com/microsoft/PSRule-vscode/blob/release/v2.9.x/extension.md", "categories": [ "Programming Languages", "Snippets" @@ -31,7 +31,7 @@ "url": "https://github.com/microsoft/PSRule-vscode.git" }, "bugs": { - "url": "https://github.com/microsoft/PSRule-vscode/issues" + "url": "https://github.com/microsoft/PSRule/issues" }, "private": true, "preview": false, @@ -462,7 +462,7 @@ "scripts": { "compile": "tsc -p ./", "watch": "tsc -watch -p ./", - "pack": "vsce package --no-git-tag-version --no-update-package-json --out out/package", + "pack": "vsce package --no-git-tag-version --no-update-package-json --readme-path extension.md --out out/package", "publish": "vsce publish", "lint": "eslint . --ext .ts,.tsx", "pretest": "npm run compile",