chocolatey · gep13 · May 24, 2024 · Apr 29, 2024 · Apr 29, 2024 · May 10, 2024
diff --git a/COMMITTERS.md b/COMMITTERS.md
@@ -152,3 +152,57 @@ References
 
  * [http://pivotallabs.com/git-rebase-onto/ (Archive)](https://web.archive.org/web/20150709101404/http://pivotallabs.com:80/git-rebase-onto/)
  * http://git-scm.com/book/ch3-6.html
+
+## Generating and Updating Cmdlet Documentation
+
+Documentation for the cmdlets in the Chocolatey.PowerShell project is maintained as `*.md` files in the [chocolatey/docs](https://github.com/chocolatey/docs) repository, under `input/en-us/create/cmdlets`.
+When making changes to a cmdlet or adding a new one, we need to ensure that those Markdown files get updated, and that those changes are propagated back to this repository in the [`Chocolatey.PowerShell.dll-help.xml`](./src/Chocolatey.PowerShell/Chocolatey.PowerShell.dll-Help.xml) file in the repository.
+
+Before working with this, be sure to clone the `chocolatey/docs` repository locally.
+If your local copy of the docs repository is not located at `../docs` relative to this folder, you will need to specify the `-DocsRepositoryPath` parameter whenever calling the `update-cmdlet-documentation.ps1` script.
+
+### Generating Documentation for a new Cmdlet
+
+Run the `update-cmdlet-documentation.ps1` script with the `-NewCommand` parameter, specifying the name of the cmdlet(s) that you've added:
+
+```powershell
+./update-cmdlet-documentation.ps1 -NewCommand Test-NewChocolateyCommand
+```
+
+Once this completes, you will get a warning that the documentation template needs to be filled out and the newly-generated documentation file will open in your default editor for `*.md` files.
+
+### Updating Documentation For an Existing Cmdlet
+
+Run the `update-cmdlet-documentation.ps1` script:
+
+```powershell
+./update-cmdlet-documentation.ps1
+```
+
+### Generating the `Chocolatey.PowerShell.dll-help.xml` External Help Documentation
+
+Once new files have been generated, in the `chocolatey/docs` repository, make any additional changes needed to the files.
+Note that these files will need to be compatible both with PlatyPS and the docs repository Markdown formatting.
+As such, for new files you will need to sure the additional frontmatter is added.
+A complete frontmatter block for these files looks like this:
+
+```md
+---
+Description: Information on Cmdlet-Name cmdlet
+external help file: Chocolatey.PowerShell.dll-Help.xml
+Module Name: Chocolatey.PowerShell
+online version: https://docs.chocolatey.org/en-us/create/functions/cmdlet-name
+Order: 70
+schema: 2.0.0
+Title: Cmdlet-Name
+xref: cmdlet-name
+---
+```
+
+Some files may also have a `RedirectFrom: [ ... ]` frontmatter entry.
+This is not required for new files, but existing files (or files added for a cmdlet that is a rewrite of a pre-existing command) should retain their existing redirects.
+
+Run the `update-cmdlet-documentation.ps1` script once more, and add the changes to the `Chocolatey.PowerShell.dll-help.xml` file to a commit.
+
+Finally, add the changes to a commit on a new branch in the `docs` repository and submit a PR for any changes there as well, alongside the PR to any changes made in this repository.
+If you are rewriting a cmdlet from a pre-existing script command, ensure you remove the old documentation file from `input/en-us/create/commands` as well, so that there are no duplicate xrefs.
diff --git a/Invoke-Tests.ps1 b/Invoke-Tests.ps1
@@ -22,7 +22,11 @@ param(
 
     # Indicate to skip packaging all of the tests packages. Useful for running tests after you've performed the tests previously.
     [switch]
-    $SkipPackaging
+    $SkipPackaging,
+
+    # Specific tag(s) of tests to run
+    [string[]]
+    $Tag
 )
 $packageRegex = 'chocolatey\.\d.*\.nupkg'
 
@@ -124,11 +128,15 @@ try {
         }
     }
 
+    if ($Tag) {
+        $PesterConfiguration.Filter.Tag = $Tag
+    }
+
     Invoke-Pester -Configuration $PesterConfiguration
 }
 finally {
     # For some reason we need to import this again... I'm not 100% sure on why...
-    Import-Module $TestPath/Chocolatey/tools/ChocolateyInstall/helpers/chocolateyInstaller.psm1
+    Import-Module $TestPath/Chocolatey/tools/ChocolateyInstall/helpers/chocolateyInstaller.psm1 -Force
     # Put back Path and Chocolatey
     Set-EnvironmentVariable -Name 'PATH' -Scope 'User' -Value $environmentVariables.UserPath
     Set-EnvironmentVariable -Name 'ChocolateyInstall' -Scope 'User' -Value $environmentVariables.UserChocolateyInstall

diff --git a/nuspec/chocolatey/chocolatey/tools/chocolateysetup.psm1 b/nuspec/chocolatey/chocolatey/tools/chocolateysetup.psm1
@@ -463,8 +463,21 @@ function Install-ChocolateyFiles {
             Get-ChildItem -Path "$_" | ForEach-Object {
                 #Write-Debug "Checking child path $_ ($($_.FullName))"
                 if (Test-Path $_.FullName) {
-                    Write-Debug "Removing $_ unless matches .log"
-                    Remove-Item $_.FullName -Exclude *.log -Recurse -Force -ErrorAction SilentlyContinue
+                    # If this is an upgrade, we can't *delete* Chocolatey.PowerShell.dll, as it will be currently loaded and thus locked.
+                    # Instead, rename it with a .old suffix. The code in the installer module will delete the .old file next time it runs.
+                    # This works similarly to how we move rather than overwriting choco.exe itself.
+                    if ($_.Name -ne "Chocolatey.PowerShell.dll") {
+                        Write-Debug "Removing $_ unless matches .log"
+                        Remove-Item $_.FullName -Exclude *.log -Recurse -Force -ErrorAction SilentlyContinue
+                    }
+                    else {
+                        $oldPath = "$($_.FullName).old"
+                        Write-Debug "Moving $_ to $oldPath"
+
+                        # Remove any still-existing Chocolatey.PowerShell.dll.old files before moving/renaming the current one.
+                        Get-Item -Path $oldPath -ErrorAction SilentlyContinue | Remove-Item -Force
+                        Move-Item $_.Fullname -Destination $oldPath
+                    }
                 }
             }
         }

diff --git a/nuspec/nuget/Chocolatey.PowerShell/Chocolatey.PowerShell.nuspec b/nuspec/nuget/Chocolatey.PowerShell/Chocolatey.PowerShell.nuspec
@@ -0,0 +1,33 @@
+<?xml version="1.0"?>
+<package xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <metadata>
+    <id>Chocolatey.PowerShell</id>
+    <version>0.9.9</version>
+    <owners>Chocolatey Software, Inc</owners>
+    <title>Chocolatey CLI PowerShell Helpers</title>
+    <authors>Chocolatey Software, Inc</authors>
+    <projectUrl>https://github.com/chocolatey/choco</projectUrl>
+    <iconUrl>https://chocolatey.org/assets/images/nupkg/chocolateyicon.png</iconUrl>
+    <licenseUrl>https://raw.githubusercontent.com/chocolatey/choco/master/LICENSE</licenseUrl>
+    <requireLicenseAcceptance>false</requireLicenseAcceptance>
+    <copyright>2024 Chocolatey Software, Inc</copyright>
+    <tags>chocolatey powershell</tags>
+    <summary>Chocolatey CLI's PowerShell helper commands</summary>
+    <description>
+Chocolatey is a package manager for Windows (like apt-get but for Windows).
+
+This is the Chocolatey PowerShell Library (API / DLL) package which contains the PowerShell helper commands used in Chocolatey CLI itself.
+
+### Information
+
+- [Chocolatey Website and Community Package Repository](https://community.chocolatey.org)
+- [Mailing List](http://groups.google.com/group/chocolatey) / [Release Announcements Only Mailing List](https://groups.google.com/group/chocolatey-announce) / [Build Status Mailing List](http://groups.google.com/group/chocolatey-build-status)
+- [Twitter](https://twitter.com/chocolateynuget) / [Facebook](https://www.facebook.com/ChocolateySoftware) / [GitHub](https://github.com/chocolatey)
+- [Blog](https://blog.chocolatey.org/) / [Newsletter](https://chocolatey.us8.list-manage1.com/subscribe?u=86a6d80146a0da7f2223712e4&amp;id=73b018498d)
+- [Documentation](https://docs.chocolatey.org/en-us/) / [Support](https://chocolatey.org/support)
+</description>
+    <releaseNotes>
+See all - https://docs.chocolatey.org/en-us/choco/release-notes
+    </releaseNotes>
+  </metadata>
+</package>
diff --git a/recipe.cake b/recipe.cake
@@ -15,7 +15,8 @@ Func<List<ILMergeConfig>> getILMergeConfigs = () =>
     var targetPlatform = "v4,C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.8";
     var assembliesToILMerge = GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/*.{exe|dll}")
                             - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/choco.exe")
-                            - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/System.Management.Automation.dll");
+                            - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/System.Management.Automation.dll")
+                            - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/Chocolatey.PowerShell.dll");
 
     Information("The following assemblies have been selected to be ILMerged for choco.exe...");
     foreach (var assemblyToILMerge in assembliesToILMerge)
@@ -34,10 +35,11 @@ Func<List<ILMergeConfig>> getILMergeConfigs = () =>
         AssemblyPaths = assembliesToILMerge });
 
     assembliesToILMerge = GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/*.{exe|dll}")
-                            - GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/choco.exe")
-                            - GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/chocolatey.dll")
-                            - GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/log4net.dll")
-                            - GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/System.Management.Automation.dll");
+                        - GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/choco.exe")
+                        - GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/chocolatey.dll")
+                        - GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/log4net.dll")
+                        - GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/System.Management.Automation.dll")
+                        - GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/Chocolatey.PowerShell.dll");
 
     Information("The following assemblies have been selected to be ILMerged for chocolatey.dll...");
     foreach (var assemblyToILMerge in assembliesToILMerge)
@@ -58,10 +60,11 @@ Func<List<ILMergeConfig>> getILMergeConfigs = () =>
     if (DirectoryExists(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/"))
     {
         var no7zAssembliesToILMerge = GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/*.{exe|dll}")
-                                - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/choco.exe")
-                                - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/System.Management.Automation.dll")
-                                - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/chocolatey.tests*.dll")
-                                - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/{Moq|nunit|Should|testcentric}*.dll");
+                                    - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/choco.exe")
+                                    - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/System.Management.Automation.dll")
+                                    - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/chocolatey.tests*.dll")
+                                    - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/{Moq|nunit|Should|testcentric}*.dll")
+                                    - GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/Chocolatey.PowerShell.dll");
 
         Information("The following assemblies have been selected to be ILMerged for choco.exe No7zip Version...");
         foreach (var assemblyToILMerge in no7zAssembliesToILMerge)
@@ -121,13 +124,15 @@ Func<FilePathCollection> getFilesToSign = () =>
     var filesToSign = GetFiles(BuildParameters.Paths.Directories.NuGetNuspecDirectory + "/lib/chocolatey.dll")
                     + GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/choco.exe")
                     + GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/tools/{checksum|shimgen}.exe")
-                    + GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/redirects/*.exe");
+                    + GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/redirects/*.exe")
+                    + GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll");
 
     if (DirectoryExists(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip"))
     {
         filesToSign += GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/choco.exe")
                     + GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/tools/{checksum|shimgen}.exe")
-                    + GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/redirects/*.exe");
+                    + GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/redirects/*.exe")
+                    + GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll");
     }
 
     Information("The following assemblies have been selected to be signed...");
@@ -172,6 +177,10 @@ Task("Prepare-Chocolatey-Packages")
 
     StartProcess(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/choco.exe", new ProcessSettings{ Arguments = "unpackself -f -y --allow-unofficial-build --run-actual" });
 
+    // Copy Chocolatey.PowerShell.dll and its help.xml file
+    CopyFile(BuildParameters.Paths.Directories.PublishedLibraries + "/Chocolatey.PowerShell/Chocolatey.PowerShell.dll", BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll");
+    CopyFile(BuildParameters.Paths.Directories.PublishedLibraries + "/Chocolatey.PowerShell/Chocolatey.PowerShell.dll-help.xml", BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll-help.xml");
+
     // Tidy up logs and config folder which are not required
     var logsDirectory = BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/logs";
     var configDirectory = BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/config";
@@ -260,6 +269,10 @@ Task("Prepare-ChocolateyNo7zip-Package")
 
     StartProcess(nuspecDirectory + "/tools/chocolateyInstall/choco.exe", new ProcessSettings{ Arguments = "unpackself -f -y --allow-unofficial-build" });
 
+    // Copy Chocolatey.PowerShell.dll and help.xml file
+    CopyFile(BuildParameters.Paths.Directories.PublishedLibraries + "/Chocolatey.PowerShell/Chocolatey.PowerShell.dll", nuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll");
+    CopyFile(BuildParameters.Paths.Directories.PublishedLibraries + "/Chocolatey.PowerShell/Chocolatey.PowerShell.dll-help.xml", nuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll-help.xml");
+
     // Tidy up logs and config folder which are not required
     var logsDirectory = nuspecDirectory + "/tools/chocolateyInstall/logs";
     var configDirectory = nuspecDirectory + "/tools/chocolateyInstall/config";