Pre-release v3.0.0-B0137 (#1735)

* Pre-release v3.0.0-B0137

* Doc updates

docs/CHANGELOG-v3.md

@@ -27,6 +27,8 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 ## Unreleased
 
+## v3.0.0-B0137 (pre-release)
+
 What's changed since pre-release v3.0.0-B0122:
 
 - General improvements:

docs/upgrade-notes.md

@@ -33,7 +33,7 @@ To resolve any issue caused by this change, you can:
 
 From _v3.0.0_, PSRule requires:
 
-- Windows PowerShell 5.1 for running as a PowerShell module. OR
+- Windows PowerShell 5.1 for running as a PowerShell module. _OR_
 - PowerShell 7.3 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).
@@ -42,16 +42,29 @@ We recommend upgrading to PowerShell 7.3 or later.
 At the time of writing, PowerShell 7.3 is the most recent version of PowerShell.
 PowerShell 7.4 is expected, and PSRule v4 will aim to support the latest version of PowerShell as the minimum requirement.
 
-### Rename of analyze CLI command to run
+### Changes to CLI commands
 
-Previously in PSRule _v2.8.0_ to _v2.9.0, the CLI command used to run rules was `analyze`.
-From _v3.0.0_, the CLI command has been renamed to `run`.
-This change was made to simplify the CLI usage and reduce confusion that might occur between locales.
+From _v3.0.0_, the CLI command names have been renamed to simplify usage.
+The following changes have been made:
 
-For example: `ps-rule analyze` is now `ps-rule run`.
+- 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
+
 ## Upgrading to v2.0.0
 
 ### Resources naming restrictions
@@ -164,7 +177,8 @@ Currently this must be set to `github.com/microsoft/PSRule/v1`.
 
 ### 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.
+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.
@@ -195,7 +209,8 @@ 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.
+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.