Support prerelease with ModuleFast and make PSResourceGet the default method

CHANGELOG.md

@@ -10,6 +10,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Update template for SECURITY.md and add it to Sampler repository as well.
+- Built module is now built in a separate folder. This is to split the paths
+  for the built module and all required modules, to avoid returning duplicate
+  modules when using `Get-Module -ListAvailable`. The templates already has
+  this configuration.
+- Update PSResourceGet to default to v1.0.1 if no version is passed in parameter
+  or specific version is configured.
+- Templates was changed to use PSResourceGet as the default method
+  of resolving dependencies. It is possible to change to the method
+  PowerShellGet & PSDepend by changing the configuration.
 
 ### Fixed
 
@@ -19,6 +28,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   point to the single version.
 - Correct description of the parameter `GalleryApiToken` in the build task
   script release.module.build.ps1. Fixes [#442](https://github.com/gaelcolas/Sampler/issues/442)
+- ModuleFast now supports resolving individual pre-release dependencies
+  that is part of _RequiredModules.psd1_. It is also possible to specify
+  [NuGet version ranges](https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges)
+  in _RequiredModules.psd1_, although then the file is not compatible with
+  PSResourceGet or PSDepend (so no fallback can happen).
 
 ## [0.117.0] - 2023-09-29
 

README.md

@@ -36,34 +36,147 @@ Check the video for a quick intro:
 
 ### Resolving dependencies
 
-#### PowerShellGet (default)
+The Sampler templates is configured to use PSResourceGet as the method of
+resolving dependencies. The property `UsePSResourceGet` is default configured
+to `$true` in the file Resolve-Dependency.psd1. If that configuration is
+removed or disabled (set to `$false`) then resolving dependencies will
+revert to PowerShellGet & PSDepend.
 
-Because we resolve dependencies from a nuget feed, whether the public
-PowerShellGallery or your private repository, a working version of PowerShellGet
-is required. Using PowerShellGet is the default if no other configuration
-is done. We recommend the latest version of PowerShellGet v2.
+The specification syntax of the file RequiredModules.psd1 works with all
+three methods of resolving dependencies.
 
-#### ModuleFast
+```powershell
+@{
+   # Gives latest release
+   Pester = 'latest'
+
+   # Gives specific release (also known as pinning version)
+   Pester = '4.10.1'
+
+   # Gives latest preview release
+   'ComputerManagementDsc' = @{
+      Version    = 'latest'
+      Parameters = @{
+         AllowPrerelease = $true
+      }
+   }
 
-It is possible to use [ModuleFast](https://github.com/JustinGrote/ModuleFast)
-to resolve dependencies. ModuleFast only works with PowerShell 7.2 or higher.
-To use ModuleFast as a replacement for PowerShellGet it is possible to
-enable it in the configuration file `Resolve-Dependency.psd1`.
-It is also possible to allow the repository to use PowerShellGet as the
-default and choose to use ModuleFast from the command line by passing
-the parameter `UseModuleFast` to the build script `build.ps1`, e.g.
-`.\build.ps1 -ResolveDependency -Tasks noop -UseModuleFast`
+   # Gives specific preview release (also known as pinning version)
+   'ComputerManagementDsc' = @{
+      Version    = '9.1.0-preview0002'
+      Parameters = @{
+         AllowPrerelease = $true
+      }
+   }
+}
+```
+
+When using the method _PowerShellGet & PSDepend_ this configuration should
+also be added to the file RequiredModules.psd1 to control the behavior
+of PSDepend. This is only required if you need to use _PowerShellGet & PSDepend_.
+It is not required for PSResourceGet or ModuleFast.
+
+```powershell
+@{
+   PSDependOptions = @{
+      AddToPath  = $true
+      Target     = 'output\RequiredModules'
+      Parameters = @{
+         Repository = 'PSGallery'
+      }
+   }
+```
 
 #### PSResourceGet
 
 It is possible to use [PSResourceGet](https://github.com/PowerShell/PSResourceGet)
-to resolve dependencies. PSResourceGet works with WIndows PowerShell and
+to resolve dependencies. PSResourceGet works with Windows PowerShell and
 PowerShell (some restrictions on versions exist). To use PSResourceGet as
 a replacement for PowerShellGet it is possible to enable it in the configuration
 file `Resolve-Dependency.psd1`. It is also possible to allow the repository
 to use PowerShellGet as the default and choose to use PSResourceGet from the
 command line by passing the parameter `UsePSResourceGet` to the build script
-`build.ps1`, e.g. `.\build.ps1 -ResolveDependency -Tasks noop -UseModuleFast`
+`build.ps1`, e.g. `.\build.ps1 -ResolveDependency -Tasks noop -UsePSResourceGet`
+
+If both PSResourceGet and ModuleFast is enabled then PSResource will be
+preferred on Windows PowerShell and PowerShell 7.2 or lower. ModuleFast
+will be preferred on PowerShell 7.3 or higher.
+
+#### ModuleFast
+
+It is possible to use [ModuleFast](https://github.com/JustinGrote/ModuleFast)
+to resolve dependencies. ModuleFast only works with PowerShell 7.3 or higher.
+To use ModuleFast as a replacement for PowerShellGet it is possible to
+enable it in the configuration file `Resolve-Dependency.psd1`.
+It is also possible to allow the repository to use PowerShellGet as the
+default and choose to use ModuleFast from the command line by passing
+the parameter `UseModuleFast` to the build script `build.ps1`, e.g.
+`.\build.ps1 -ResolveDependency -Tasks noop -UseModuleFast`.
+
+If both PSResourceGet and ModuleFast is enabled then ModuleFast will be
+preferred on PowerShell 7.3 or higher. PSResource will be preferred
+on Windows PowerShell and PowerShell 7.2 or lower.
+
+When using ModuleFast as the only method there is more options to specify
+modules in the file RequiredModules.psd1. This syntax will limit resolving
+dependencies to just ModuleFast (and PowerShell 7.3 or higher) as they are
+not supported by the other methods. See the comment-based help of the command
+[`Install-ModuleFast`](https://github.com/JustinGrote/ModuleFast/blob/main/ModuleFast.psm1)
+for more information of the available syntax.
+
+```powershell
+@{
+   # Gives the latest release
+   'ComputerManagementDsc' =  'latest'
+
+   # Gives the specific release
+   'ComputerManagementDsc' =  '9.0.0'
+
+   # Gives the latest patch release for v9.0
+   'ComputerManagementDsc' =  ':9.0.*'
+
+   # Gives the latest preview release
+   'ComputerManagementDsc' =  '!'
+
+   # Gives the latest release (including previews) that is higher that v9.0.0
+   'ComputerManagementDsc' =  '!>9.0.0'
+
+   # Must be exactly 9.1.0-preview0002
+   'ComputerManagementDsc' =  '9.1.0-preview0002'
+   'ComputerManagementDsc' =  '@9.1.0-preview0002'
+   'ComputerManagementDsc' =  ':9.1.0-preview0002'
+   'ComputerManagementDsc' =  ':[9.1.0-preview0002]'
+
+   # Must be a higher version than 9.1.0-preview0002
+   'ComputerManagementDsc' =  '>9.1.0-preview0002'
+
+   # Must be a lower version than 9.1.0-preview0002
+   'ComputerManagementDsc' =  '<9.1.0-preview0002'
+
+   # Must be a lower version than or equal to 9.1.0-preview0002
+   'ComputerManagementDsc' =  '<=9.1.0-preview0002'
+
+   # Must be a higher version than or equal to 9.1.0-preview0002
+   'ComputerManagementDsc' =  '>=9.1.0-preview0002'
+
+   # Exact range, exclusive. Must be lower version than 9.2.0. 9.2.0 is not allowed.
+   'ComputerManagementDsc' =  ':(,9.2.0)'
+
+   # Exact range, exclusive. Must be higher version than 9.0.0. 9.0.0 is not allowed.
+   'ComputerManagementDsc' =  ':(9.0.0,)'
+
+   # Exact range, inclusive. Must be version than 9.0.0 or higher up to or equal to 9.2.0.
+   'ComputerManagementDsc' =  ':[9.0.0,9.2.0]'
+}
+
+```
+
+#### PowerShellGet & PSDepend
+
+Because we resolve dependencies from a nuget feed, whether the public
+PowerShell Gallery or your private repository, a working version of PowerShellGet
+is required. Using PowerShellGet is the default if no other configuration
+is done. We recommend the latest version of PowerShellGet v2.
 
 ### Managing the Module versions (optional)
 
@@ -239,10 +352,13 @@ minimal environmental dependencies.
 graph LR
 
 RD[Resolve dependencies] --> Method{Method?}
-Method{Method?} -->|"(Default)"| PowerShellGet(["PowerShellGet"])
+Method{Method?} -->|"(Legacy, to use,
+disable other
+methods)"| PowerShellGet(["PowerShellGet"])
 Method -->|"parameter
 -UseModuleFast"| ModuleFast(["ModuleFast"])
-Method -->|"parameter
+Method -->|"(Default),
+parameter
 -UsePSResourceGet"| PSResourceGet(["PSResourceGet"])
 PowerShellGet -->|"Invoke-PSDepend"| InvokeRD
 ModuleFast -->|"Install-ModuleFast"| InvokeRD

RequiredModules.psd1

@@ -1,9 +1,16 @@
 @{
-    PSDependOptions             = @{
-        AddToPath  = $true
-        Target     = 'output\RequiredModules'
-        Parameters = @{}
-    }
+    <#
+        This is only required if you need to use the method PowerShellGet & PSDepend
+        It is not required for PSResourceGet or ModuleFast (and will be ignored).
+        See Resolve-Dependency.psd1 on how to enable methods.
+    #>
+    #PSDependOptions                = @{
+    #    AddToPath  = $true
+    #    Target     = 'output\RequiredModules'
+    #    Parameters = @{
+    #        Repository = 'PSGallery'
+    #    }
+    #}
 
     InvokeBuild                 = 'latest'
     PSScriptAnalyzer            = 'latest'