diff --git a/README.md b/README.md index 38914cce49..3546b2402e 100644 --- a/README.md +++ b/README.md @@ -370,7 +370,7 @@ For a list of projects and integrations see [Related projects][10]. ## Changes and versioning This repository uses [semantic versioning](http://semver.org/) to declare breaking changes. -For details please see the [changes and versioning](https://microsoft.github.io/PSRule/v2/versioning/). +For details please see the [changes and versioning](https://microsoft.github.io/PSRule/v3/versioning/). ## Contributing diff --git a/docs/assets/stylesheets/extra.css b/docs/assets/stylesheets/extra.css index db7fbd603c..b5c44546c0 100644 --- a/docs/assets/stylesheets/extra.css +++ b/docs/assets/stylesheets/extra.css @@ -28,9 +28,13 @@ } :root { - --md-admonition-icon--experimental: url('data:image/svg+xml;charset=utf-8,') + --md-admonition-icon--experimental: url('data:image/svg+xml;charset=utf-8,'); + --md-admonition-icon--learn: url('data:image/svg+xml;charset=utf-8,'); + --md-admonition-icon--message: url('data:image/svg+xml;charset=utf-8,'); + --md-admonition-icon--security: url('data:image/svg+xml;charset=utf-8,'); } +/* experimental */ .md-typeset .admonition.experimental, .md-typeset details.experimental { border-color: rgb(124, 77, 255) @@ -39,7 +43,6 @@ .md-typeset .experimental>.admonition-title, .md-typeset .experimental>summary { background-color: rgba(124, 77, 255, .1); - ; border-color: rgb(124, 77, 255); } @@ -50,8 +53,78 @@ mask-image: var(--md-admonition-icon--experimental); } -aside.md-banner { - overflow: auto; - color: var(--md-warning-fg-color); - background-color: var(--md-warning-bg-color); +/* learn */ +.md-typeset .admonition.learn, +.md-typeset details.learn { + border-color: rgb(0, 191, 165) +} + +.md-typeset .learn>.admonition-title, +.md-typeset .learn>summary { + background-color: rgba(0, 191, 165, .1); + border-color: rgb(0, 191, 165) +} + +.md-typeset .learn>.admonition-title::before, +.md-typeset .learn>summary::before { + background-color: rgb(0, 191, 165); + -webkit-mask-image: var(--md-admonition-icon--learn); + mask-image: var(--md-admonition-icon--learn); +} + +/* message */ +.md-typeset .admonition.message, +.md-typeset details.message { + border-color: rgb(0, 184, 212) +} + +.md-typeset .message>.admonition-title, +.md-typeset .message>summary { + background-color: rgba(0, 184, 212, .1); + border-color: rgb(0, 184, 212); +} + +.md-typeset .message>.admonition-title::before, +.md-typeset .message>summary::before { + background-color: rgb(0, 184, 212); + -webkit-mask-image: var(--md-admonition-icon--message); + mask-image: var(--md-admonition-icon--message); +} + +/* security */ +.md-typeset .admonition.security, +.md-typeset details.security { + border-color: rgb(32, 148, 243) +} + +.md-typeset .security>.admonition-title, +.md-typeset .security>summary { + background-color: rgba(32, 148, 243, .1); + border-color: rgb(32, 148, 243) +} + +.md-typeset .security>.admonition-title::before, +.md-typeset .security>summary::before { + background-color: rgb(32, 148, 243); + -webkit-mask-image: var(--md-admonition-icon--security); + mask-image: var(--md-admonition-icon--security); +} + +/* badges */ +.badge { + font-size: .85em +} + +.md-typeset .badge__icon { + background: var(--md-accent-fg-color--transparent); + padding: .2rem +} + +.md-typeset .badge__icon:last-child { + border-radius: .1rem +} + +.md-typeset .badge__text { + box-shadow: 0 0 0 1px inset var(--md-accent-fg-color--transparent); + padding: .2rem .3rem } diff --git a/docs/deprecations.md b/docs/deprecations.md index b983ee0f29..d2b840a115 100644 --- a/docs/deprecations.md +++ b/docs/deprecations.md @@ -5,6 +5,8 @@ discussion: false # Deprecations +This article contains notes on features that are deprecated in PSRule v3.0.0 and later. + ## Deprecations for v3 ### Execution options @@ -112,28 +114,3 @@ Prior to v3, a custom binding PowerShell script block could be used to perform c This feature was hard to use and obsolete for most common use cases. Alternatively, configure `Binding.TargetName` and `Binding.TargetType` options to use the built-in binder. - -## Deprecations for v2 - -### Default baseline by module manifest - -When packaging baselines in a module, you may want to specify a default baseline. -PSRule _v1.9.0_ added support for setting the default baseline in a module configuration. - -Previously a default baseline could be set by specifying the baseline in the module manifest. -From _v1.9.0_ this is deprecated and will be removed from _v2_. - -For details on how to migrate to the new default baseline option, continue reading the [upgrade notes][1]. - - [1]: upgrade-notes.md#setting-default-module-baseline - -### Resources without an API version - -When creating YAML and JSON resources you define a resource by specifying the `apiVersion` and `kind`. -To allow new schema versions for resources to be introduced in the future, an `apiVersion` was introduced. -For backwards compatibility, resources without an `apiVersion` deprecated but supported. -From _v2_ resources without an `apiVersion` will be ignored. - -For details on how to add an `apiVersion` to a resource, continue reading the [upgrade notes][2]. - - [2]: upgrade-notes.md#setting-resource-api-version diff --git a/docs/setup/vscode.md b/docs/setup/vscode.md index ef73487a3b..28108b1b15 100644 --- a/docs/setup/vscode.md +++ b/docs/setup/vscode.md @@ -12,7 +12,7 @@ The Visual Studio Code extension includes a built-in tasks and configuration sch 1. Download and install Visual Studio Code. 2. Install the [PSRule extension from the marketplace][1]. -Alternatively you can separately download the extension as a packaged `.vsix` file and install it locally. +Alternatively, you can separately download the extension as a packaged `.vsix` file and install it locally. [1]: https://marketplace.visualstudio.com/items?itemName=ps-rule.vscode-ps-rule @@ -23,7 +23,7 @@ Each extension update includes all the key components to make PSRule work withou By default, Visual Studio Code automatically updates extensions installed from the marketplace when updates are available. -!!! Note +!!! Learn You can disable automatic updates of Visual Studio Code extensions if you prefer to update PSRule on your own schedule. It is also possible to switch to an older version of PSRule from v3. diff --git a/docs/upgrade-notes.md b/docs/upgrade-notes.md index 2317812f1e..ece1669c65 100644 --- a/docs/upgrade-notes.md +++ b/docs/upgrade-notes.md @@ -1,16 +1,14 @@ --- -title: Notes for upgrading between PSRule versions +title: Notes for upgrading to PSRule v3.0.0 author: BernieWhite discussion: false --- # Upgrade notes -This document contains notes to help upgrade from previous versions of PSRule. +This article contains notes to help upgrade to PSRule v3.0.0 and later. -## Upgrading to v3.0.0 - -### Unbound object names +## Unbound object names When an object is processed by PSRule, it is assigned a name. This name is used to identify the object in the output and to suppress the object from future processing. @@ -29,7 +27,7 @@ To resolve any issue caused by this change, you can: [1]: https://aka.ms/ps-rule/options#bindingtargetname [2]: https://aka.ms/ps-rule/options#suppression -### Using PowerShell 7.4 or later +## Using PowerShell 7.4 or later From _v3.0.0_, PSRule requires: @@ -39,7 +37,7 @@ From _v3.0.0_, PSRule requires: Support for Windows PowerShell 5.1 is deprecated and will be removed in a future release of PSRule (v4). We recommend upgrading to PowerShell 7.4 or later. -### Changes to CLI commands +## Changes to CLI commands From _v3.0.0_, the CLI command names have been renamed to simplify usage. The following changes have been made: @@ -62,7 +60,7 @@ From _v3.0.0_, the `module restore` command installs modules based on: [5]: concepts/cli/module.md [6]: concepts/lockfile.md -### Version and APIVersion accept stable +## Version and APIVersion accept stable Prior to _v3.0.0_, some usage of `version` and `apiVersion` accepted pre-release versions by default. For example: @@ -98,274 +96,3 @@ spec: apiVersion: '' includePrerelease: true ``` - -## Upgrading to v2.0.0 - -### Resources naming restrictions - -When naming resources such as rules or selectors, the following restrictions apply: - -- **Use between 3 and 128 characters** — This is the minimum and maximum length of a resource name. -- **Only use allowed characters** — - To preserve consistency between file systems, some characters are not permitted. - Dots, hyphens, and underscores are not permitted at the start and end of the name. - Additionally some characters are restricted for future use. - The following characters are not permitted: - - `<` (less than) - - `>` (greater than) - - `:` (colon) - - `/` (forward slash) - - `\` (backslash) - - `|` (vertical bar or pipe) - - `?` (question mark) - - `*` (asterisk) - - `"` (double quote) - - `'` (single quote) - - `` ` `` (backtick) - - `+` (plus) - - `@` (at sign) - - Integer value zero, sometimes referred to as the ASCII NUL character. - - Characters whose integer representations are in the range from 1 through 31. - -Prior to _v2.0.0_, there was no specific naming restriction for resources. -However functionally PSRule and downstream components could not support all resource names. -To avoid confusion, we have decided to restrict resource names to a specific set of characters. - -From _v2.0.0_, resource names that do not meet the naming restrictions will generate an error. - -```text title="Regular expression for valid resource names" -^[^<>:/\\|?*"'`+@._\-\x00-\x1F][^<>:/\\|?*"'`+@\x00-\x1F]{1,126}[^<>:/\\|?*"'`+@._\-\x00-\x1F]$ -``` - -### Setting default module baseline - -When packaging rules in a module, you can set the default baseline. -The default baseline from the module will be automatically used unless overridden. - -Prior to _v1.9.0_ the default baseline was set by configuring the module manifest `.psd1` file. -From _v1.9.0_ the default baseline can be configured by within a module configuration. -Using module configuration is the recommended method. -Setting the default baseline from module manifest and has been removed from _v2.0.0_. - -A module configuration can be defined in YAML. - -!!! Example - - ```yaml hl_lines="8-9" - --- - # Synopsis: Example module configuration for Enterprise.Rules module. - apiVersion: github.com/microsoft/PSRule/v1 - kind: ModuleConfig - metadata: - name: Enterprise.Rules - spec: - rule: - baseline: Enterprise.Default - ``` - -### Setting resource API version - -When creating YAML and JSON resources you define a resource by specifying the `apiVersion` and `kind`. -An `apiVersion` was added as a requirement from _v1.2.0_. -For compatibility, resources without an `apiVersion` were supported however deprecated for removal. -This has now been removed from _v2.0.0_. - -When defining resource specify an `apiVersion`. -Currently this must be set to `github.com/microsoft/PSRule/v1`. - -=== "YAML" - - ```yaml hl_lines="3-4" - --- - # Synopsis: An example rule to require TLS. - apiVersion: github.com/microsoft/PSRule/v1 - kind: Rule - metadata: - name: 'Local.YAML.RequireTLS' - spec: - condition: - field: 'configure.supportsHttpsTrafficOnly' - equals: true - ``` - -=== "JSON" - - ```json hl_lines="4-5" - [ - { - // Synopsis: An example rule to require TLS. - "apiVersion": "github.com/microsoft/PSRule/v1", - "kind": "Rule", - "metadata": { - "name": "Local.JSON.RequireTLS" - }, - "spec": { - "condition": { - "field": "configure.supportsHttpsTrafficOnly", - "equals": true - } - } - } - ] - ``` - -### Change in source file discovery for Get-PSRuleHelp - -Previously in PSRule _v1.11.0_ and prior versions, -rules would show up twice when running `Get-PSRuleHelp` in the context of a module and in the same working directory of the module. -This behavior has now been removed from _v2.0.0_. - -Module files are now preferred over loose files, and rules are only shown once in the output. -Any duplicate rule names from loose files are outputted as a warning instead. - -The old behavior: - -```powershell -Name ModuleName Synopsis ----- ---------- -------- -M1.Rule1 This is the default -M1.Rule2 This is the default -M1.Rule1 TestModule Synopsis en-AU. -M1.Rule2 TestModule This is the default -``` - -The new behavior: - -```powershell -WARNING: A rule with the same name 'M1.Rule1' already exists. -WARNING: A rule with the same name 'M1.Rule2' already exists. - -Name ModuleName Synopsis ----- ---------- -------- -M1.Rule1 TestModule Synopsis en-AU. -M1.Rule2 TestModule This is the default -``` - -### Require source discovery from current working directory to be explicitly included - -Previously in PSRule _v1.11.0_ and prior versions, -rule sources from the current working directory without the `-Path` and `-Module` parameters were automatically included. -This behavior has now been removed from _v2.0.0_. - -Rules sources in the current working directory are only included if `-Path .` or `-Path $PWD` is specified. - -The old behavior: - -```powershell title="PowerShell" -Set-Location docs\scenarios\azure-resources -Get-PSRule - -RuleName ModuleName Synopsis --------- ---------- -------- -appServicePlan.MinInstanceCount App Service Plan has multiple instances -appServicePlan.MinPlan Use at least a Standard App Service Plan -appServiceApp.ARRAffinity Disable client affinity for stateless services -appServiceApp.UseHTTPS Use HTTPS only -storageAccounts.UseHttps Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB -storageAccounts.UseEncryption Use at-rest storage encryption -``` - -The new behavior: - -```powershell title="PowerShell" -Set-Location docs\scenarios\azure-resources -Get-PSRule - -# No output, need to specify -Path explicitly - -Get-PSRule -Path $PWD - -RuleName ModuleName Synopsis --------- ---------- -------- -appServicePlan.MinInstanceCount App Service Plan has multiple instances -appServicePlan.MinPlan Use at least a Standard App Service Plan -appServiceApp.ARRAffinity Disable client affinity for stateless services -appServiceApp.UseHTTPS Use HTTPS only -storageAccounts.UseHttps Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB -storageAccounts.UseEncryption -``` - -## Upgrading to v1.4.0 - -Follow these notes to upgrade to PSRule _v1.4.0_ from previous versions. - -### Change in default output styles - -Previously in PSRule _v1.3.0_ and prior the default style when using `Assert-PSRule` was `Client`. -From _v1.4.0_ PSRule now defaults to `Detect`. - -The `Detect` output style falls back to `Client` however may detect one of the following styles instead: - -- `AzurePipelines` - Output is written for integration Azure Pipelines. -- `GitHubActions` - Output is written for integration GitHub Actions. -- `VisualStudioCode` - Output is written for integration with Visual Studio Code. - -Detect uses the following logic: - -1. If the `TF_BUILD` environment variable is set to `true`, `AzurePipelines` will be used. -2. If the `GITHUB_ACTIONS` environment variable is set to `true`, `GitHubActions` will be used. -3. If the `TERM_PROGRAM` environment variable is set to `vscode`, `VisualStudioCode` will be used. -4. Use `Client`. - -To force usage of the `Client` output style set the `Output.Style` option. -For example: - -```yaml title="ps-rule.yaml" -# YAML: Using the output/style property -output: - style: Client -``` - -```bash -# Bash: Using environment variable -export PSRULE_OUTPUT_STYLE=Client -``` - -```yaml title="GitHub Actions" -# GitHub Actions: Using environment variable -env: - PSRULE_OUTPUT_STYLE: Client -``` - -```yaml title="Azure Pipelines" -# Azure Pipelines: Using environment variable -variables: -- name: PSRULE_OUTPUT_STYLE - value: Client -``` - -## Upgrading to v1.0.0 - -Follow these notes to upgrade to PSRule _v1.0.0_ from previous versions. - -### Replaced $Rule target properties - -Previously in PSRule _v0.22.0_ and prior the `$Rule` automatic variable had the following properties: - -- `TargetName` -- `TargetType` -- `TargetObject` - -For example: - -```powershell title="PowerShell rules" -Rule 'Rule1' { - $Rule.TargetName -eq 'Name1'; - $Rule.TargetType -eq '.json'; - $Rule.TargetObject.someProperty -eq 1; -} -``` - -In _v1.0.0_ these properties have been removed after being deprecated in _v0.12.0_. -These properties are instead available on the `$PSRule` variable. -Rules referencing the deprecated properties of `$Rule` must be updated. - -For example: - -```powershell title="PowerShell rules" -Rule 'Rule1' { - $PSRule.TargetName -eq 'Name1'; - $PSRule.TargetType -eq '.json'; - $PSRule.TargetObject.someProperty -eq 1; -} -``` diff --git a/docs/versioning.md b/docs/versioning.md index 60e3a5246e..479a6cd51d 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -5,16 +5,49 @@ discussion: false # Changes and versioning -PSRule uses [semantic versioning][1] to declare breaking changes. -The latest module version can be installed from the PowerShell Gallery. -For a list of module changes please see the [change log][2]. +This article briefly covers the conventions/ terminology used for versioning and describing changes in PSRule. + +## Semantic versioning + +PSRule generally uses [semantic versioning][1] for each release **stable** and **pre-release**. +However not all platforms we publish to support semantic versioning. +Continue reading to understand how we use semantic versioning in PSRule. + +You can read more about semantic versioning at [semver.org][1]. [1]: https://semver.org/ + +For a list of changes please see the [change log][2]. + [2]: https://aka.ms/ps-rule/changelog +## Stable releases + +Stable releases are released periodically and are considered production ready. +These releases are generally feature complete and have been tested by the PSRule team. + +Each stable release uses a version number in the format `major.minor.patch`. +For example, `3.0.0`. + +Generally we aim to fix any issues or bugs in the next stable release, however that is not always possible. +If you experience an issue with a stable release please let us know by logging an issue as a [bug][3]. +Also, consider voting up (👍) an issue that is important to you to help us prioritize work. + +To install a stable release see [Setting up PSRule][4]. + + [3]: https://github.com/microsoft/PSRule/issues + [4]: setup.md + ## Pre-releases -Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. +Pre-release versions are created on major commits leading up to a stable release. + +Each pre-release uses a version number in the format `major.minor.patch-prerelease`. +For example, `3.0.0-B0100`. + +However, Visual Studio Marketplace does not support adding a pre-release identifier `-prerelease`. +Instead, a pre-release version is published in the format `nnnn.nnnn.nnnn` and marked as a pre-release. + Module versions and change log details for pre-releases will be removed as stable releases are made available. !!! Important @@ -38,5 +71,3 @@ Experimental features may ship in stable releases, however to use them you may n ## Reporting bugs If you experience an issue with an pre-release or experimental feature please let us know by logging an issue as a [bug][3]. - - [3]: https://github.com/microsoft/PSRule/issues