Fix banner (microsoft#2694)

docs/assets/stylesheets/extra.css

@@ -128,3 +128,11 @@
   box-shadow: 0 0 0 1px inset var(--md-accent-fg-color--transparent);
   padding: .2rem .3rem
 }
+
+/* Add banner */
+
+aside.md-banner {
+  overflow: auto;
+  color: var(--md-warning-fg-color);
+  background-color: var(--md-warning-bg-color);
+}

docs/deprecations.md

@@ -1,15 +1,14 @@
 ---
+description: This article contains notes on breaking changes in PSRule v3 to help you upgrade from a previous version.
 author: BernieWhite
 discussion: false
 ---
 
-# Deprecations
+# Deprecations and breaking changes
 
-This article contains notes on features that are deprecated in PSRule v3.0.0 and later.
+This article contains notes on breaking changes in PSRule v3 to help you upgrade from a previous version.
 
-## Deprecations for v3
-
-### Execution options
+## Execution options
 
 PSRule provides a number of execution options that control logging of certain events.
 In many cases these options turn a warning on or off.
@@ -45,7 +44,7 @@ The following execution options have been deprecated and will be removed from _v
     You do not need to configure both options.
     If you have the deprecated option configured, switch to the new option.
 
-### Git Head input object
+## Git Head input object
 
 Previously when the `Input.Format` option was set to `File` the `.git/HEAD` file was emitted as an input object.
 The original purpose of this feature was to allow conventions to run once against the root of the repository.
@@ -56,7 +55,7 @@ From _v3_ the `.git/HEAD` file will no longer be emitted as an input object.
 Consider adding or updating a convention that uses the `-Initialize` block to emit run initialization logic.
 Yon can also use the `-Initialize` block to emit a custom object to the pipeline by using the `$PSRule.ImportWithType` method.
 
-### Rule output object
+## Rule output object
 
 Several properties of the rule object have been renamed to improve consistency with other objects.
 Previously rules returned by `Get-PSRule` returned a rule object which included the following properties:
@@ -80,7 +79,7 @@ From _v3_ these properties will be removed.
 These changes do not affect normal usage of PSRule.
 Supporting scripts that directly use the old names may not work correctly until you update these names.
 
-### Language block interface
+## Language block interface
 
 Several properties of Baselines and Selectors have been renamed to improve consistency.
 
@@ -97,7 +96,7 @@ From _v3_ these properties will be removed.
 These changes do not affect normal usage of PSRule.
 Supporting scripts that directly use the old names may not work correctly until you update these names.
 
-### Binding configuration in baselines
+## Binding configuration in baselines
 
 Prior to v3, a baseline could configure a binding configuration to modify how objects are recognized by name, type, and scope.
 This existed to support scenarios before a module configuration and language scopes where core to how PSRule operates.
@@ -108,9 +107,99 @@ This existed to support scenarios before a module configuration and language sco
 
 Configuring binding configuration on a baseline is removed from PSRule v3.
 
-### Binding hooks
+## Binding hooks
 
 Prior to v3, a custom binding PowerShell script block could be used to perform custom binding inline.
 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.
+
+
+## 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.
+
+Prior to _v3.0.0_, the name was generated using a SHA-1 hash of the object.
+The SHA-1 algorithm is no longer considered secure and has been replaced with SHA-512.
+
+From _v3.0.0_, if the name of an object can not be determined, the SHA-512 hash of the object will be used.
+Any objects that have previously been suppressed with a name based on a SHA-1 hash will no longer be suppressed.
+
+To resolve any issue caused by this change, you can:
+
+1. Configure binding by setting the [Binding.TargetName][1] option to set an alternative property to use as the name. _OR_
+2. Update any existing keys set with the [Suppression][2] option to use the new SHA-512 hash.
+
+  [1]: https://aka.ms/ps-rule/options#bindingtargetname
+  [2]: https://aka.ms/ps-rule/options#suppression
+
+## Using PowerShell 7.4 or later
+
+From _v3.0.0_, PSRule requires:
+
+- Windows PowerShell 5.1 for running as a PowerShell module. _OR_
+- PowerShell 7.4 or later for development, building locally, or running as a PowerShell module.
+
+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
+
+From _v3.0.0_, the CLI command names have been renamed to simplify usage.
+The following changes have been made:
+
+- To run rules, use `run` instead of `analyze`. i.e. `ps-rule run`.
+- To restore modules for a workspace, use `module restore` instead of `restore`. i.e. `ps-rule module restore`.
+
+The `run` command provides similar output to the `Assert-PSRule` cmdlet in PowerShell.
+
+Previously the `restore` command installed modules based on the configuration of the [Requires][3] option.
+From _v3.0.0_, the `module restore` command installs modules based on:
+
+- The module lock file `ps-rule.lock.json` if set.
+  Use `module` [CLI commands][5] to manage the [lock file][6]. _AND_
+- Modules defined in the [Include.Module][4] option, if set.
+  Additionally the [Requires][3] option is used to constrain the version of modules installed.
+
+  [3]: concepts/PSRule/en-US/about_PSRule_Options.md#requires
+  [4]: concepts/PSRule/en-US/about_PSRule_Options.md#includemodule
+  [5]: concepts/cli/module.md
+  [6]: concepts/lockfile.md
+
+## Version and APIVersion accept stable
+
+Prior to _v3.0.0_, some usage of `version` and `apiVersion` accepted pre-release versions by default.
+For example:
+
+```yaml
+---
+# Synopsis: Any version example
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: PreviousAnyVersionExample
+spec:
+  if:
+    field: dateVersion
+    apiVersion: ''
+```
+
+When `apiVersion` is empty any version is accepted including pre-releases.
+
+From _v3.0.0_ pre-release versions are not accepted by default.
+Set the `includePrerelease` property to `true`.
+
+```yaml
+---
+# Synopsis: Test comparison with apiVersion.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: AnyVersion
+spec:
+  if:
+    field: dateVersion
+    apiVersion: ''
+    includePrerelease: true
+```

docs/hooks/maml_formatting.py

@@ -42,7 +42,7 @@ def on_page_markdown(markdown: str, page: mkdocs.structure.nav.Page, config: mkd
     markdown = markdown.replace("# PSRule_Variables", "# Variables")
 
     # Rules
-    if page.canonical_url.__contains__("/concepts/PSRule/") or page.canonical_url.__contains__("/keywords/PSRule/"):
+    if page.canonical_url.__contains__("/concepts/PSRule/") or page.canonical_url.__contains__("/keywords/PSRule/") or page.canonical_url.__contains__("/commands/PSRule/"):
         markdown = markdown.replace("## SYNOPSIS", "")
         markdown = markdown.replace("## DESCRIPTION", "## Description")
         markdown = markdown.replace("## RECOMMENDATION", "## Recommendation")

docs/versioning.md

@@ -36,7 +36,7 @@ Also, consider voting up (👍) an issue that is important to you to help us pri
 To install a stable release see [Setting up PSRule][4].
 
   [3]: https://github.com/microsoft/PSRule/issues
-  [4]: setup.md
+  [4]: setup/index.md
 
 ## Pre-releases
 

mkdocs.yml

@@ -84,7 +84,6 @@ nav:
   - Updates:
       # - January 2025: updates/v3.0.md
       - Change log: 'CHANGELOG-v3.md'
-      - Upgrade notes: upgrade-notes.md
       - Deprecations: deprecations.md
       - Changes and versioning: versioning.md
   - Reference:
@@ -164,6 +163,7 @@ plugins:
         'install-instructions.md': 'setup/index.md'
         'install.md': 'setup/index.md'
         'changelog.md': 'CHANGELOG-v3.md'
+        'upgrade-notes.md': 'deprecations.md'
 
 hooks:
   - docs/hooks/maml_formatting.py