Skip to content

Commit 2ab635e

Browse files
gep13gep13
authored
Merge pull request #3440 from vexx32/uninstall-chocolateypath-cmdlets
(#310, #3318) Add Uninstall-ChocolateyPath cmdlet & rewrite associated functions as cmdlets
2 parents 118cb4b + a91901f commit 2ab635e

File tree

47 files changed

+2903
-1890
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+2903
-1890
lines changed

‎COMMITTERS.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,3 +152,57 @@ References
152152

153153
* [http://pivotallabs.com/git-rebase-onto/ (Archive)](https://web.archive.org/web/20150709101404/http://pivotallabs.com:80/git-rebase-onto/)
154154
* http://git-scm.com/book/ch3-6.html
155+
156+
## Generating and Updating Cmdlet Documentation
157+
158+
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`.
159+
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.
160+
161+
Before working with this, be sure to clone the `chocolatey/docs` repository locally.
162+
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.
163+
164+
### Generating Documentation for a new Cmdlet
165+
166+
Run the `update-cmdlet-documentation.ps1` script with the `-NewCommand` parameter, specifying the name of the cmdlet(s) that you've added:
167+
168+
```powershell
169+
./update-cmdlet-documentation.ps1 -NewCommand Test-NewChocolateyCommand
170+
```
171+
172+
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.
173+
174+
### Updating Documentation For an Existing Cmdlet
175+
176+
Run the `update-cmdlet-documentation.ps1` script:
177+
178+
```powershell
179+
./update-cmdlet-documentation.ps1
180+
```
181+
182+
### Generating the `Chocolatey.PowerShell.dll-help.xml` External Help Documentation
183+
184+
Once new files have been generated, in the `chocolatey/docs` repository, make any additional changes needed to the files.
185+
Note that these files will need to be compatible both with PlatyPS and the docs repository Markdown formatting.
186+
As such, for new files you will need to sure the additional frontmatter is added.
187+
A complete frontmatter block for these files looks like this:
188+
189+
```md
190+
---
191+
Description: Information on Cmdlet-Name cmdlet
192+
external help file: Chocolatey.PowerShell.dll-Help.xml
193+
Module Name: Chocolatey.PowerShell
194+
online version: https://docs.chocolatey.org/en-us/create/functions/cmdlet-name
195+
Order: 70
196+
schema: 2.0.0
197+
Title: Cmdlet-Name
198+
xref: cmdlet-name
199+
---
200+
```
201+
202+
Some files may also have a `RedirectFrom: [ ... ]` frontmatter entry.
203+
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.
204+
205+
Run the `update-cmdlet-documentation.ps1` script once more, and add the changes to the `Chocolatey.PowerShell.dll-help.xml` file to a commit.
206+
207+
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.
208+
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.

‎Invoke-Tests.ps1‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,11 @@ param(
2222

2323
# Indicate to skip packaging all of the tests packages. Useful for running tests after you've performed the tests previously.
2424
[switch]
25-
$SkipPackaging
25+
$SkipPackaging,
26+
27+
# Specific tag(s) of tests to run
28+
[string[]]
29+
$Tag
2630
)
2731
$packageRegex = 'chocolatey\.\d.*\.nupkg'
2832

@@ -124,11 +128,15 @@ try {
124128
}
125129
}
126130

131+
if ($Tag) {
132+
$PesterConfiguration.Filter.Tag = $Tag
133+
}
134+
127135
Invoke-Pester -Configuration $PesterConfiguration
128136
}
129137
finally {
130138
# For some reason we need to import this again... I'm not 100% sure on why...
131-
Import-Module $TestPath/Chocolatey/tools/ChocolateyInstall/helpers/chocolateyInstaller.psm1
139+
Import-Module $TestPath/Chocolatey/tools/ChocolateyInstall/helpers/chocolateyInstaller.psm1 -Force
132140
# Put back Path and Chocolatey
133141
Set-EnvironmentVariable -Name 'PATH' -Scope 'User' -Value $environmentVariables.UserPath
134142
Set-EnvironmentVariable -Name 'ChocolateyInstall' -Scope 'User' -Value $environmentVariables.UserChocolateyInstall

‎nuspec/chocolatey/chocolatey/tools/chocolateysetup.psm1‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -463,8 +463,21 @@ function Install-ChocolateyFiles {
463463
Get-ChildItem -Path "$_" | ForEach-Object {
464464
#Write-Debug "Checking child path $_ ($($_.FullName))"
465465
if (Test-Path $_.FullName) {
466-
Write-Debug "Removing $_ unless matches .log"
467-
Remove-Item $_.FullName -Exclude *.log -Recurse -Force -ErrorAction SilentlyContinue
466+
# If this is an upgrade, we can't *delete* Chocolatey.PowerShell.dll, as it will be currently loaded and thus locked.
467+
# Instead, rename it with a .old suffix. The code in the installer module will delete the .old file next time it runs.
468+
# This works similarly to how we move rather than overwriting choco.exe itself.
469+
if ($_.Name -ne "Chocolatey.PowerShell.dll") {
470+
Write-Debug "Removing $_ unless matches .log"
471+
Remove-Item $_.FullName -Exclude *.log -Recurse -Force -ErrorAction SilentlyContinue
472+
}
473+
else {
474+
$oldPath = "$($_.FullName).old"
475+
Write-Debug "Moving $_ to $oldPath"
476+
477+
# Remove any still-existing Chocolatey.PowerShell.dll.old files before moving/renaming the current one.
478+
Get-Item -Path $oldPath -ErrorAction SilentlyContinue | Remove-Item -Force
479+
Move-Item $_.Fullname -Destination $oldPath
480+
}
468481
}
469482
}
470483
}

‎nuspec/nuget/Chocolatey.PowerShell/Chocolatey.PowerShell.nuspec‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<?xml version="1.0"?>
2+
<package xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
3+
<metadata>
4+
<id>Chocolatey.PowerShell</id>
5+
<version>0.9.9</version>
6+
<owners>Chocolatey Software, Inc</owners>
7+
<title>Chocolatey CLI PowerShell Helpers</title>
8+
<authors>Chocolatey Software, Inc</authors>
9+
<projectUrl>https://github.com/chocolatey/choco</projectUrl>
10+
<iconUrl>https://chocolatey.org/assets/images/nupkg/chocolateyicon.png</iconUrl>
11+
<licenseUrl>https://raw.githubusercontent.com/chocolatey/choco/master/LICENSE</licenseUrl>
12+
<requireLicenseAcceptance>false</requireLicenseAcceptance>
13+
<copyright>2024 Chocolatey Software, Inc</copyright>
14+
<tags>chocolatey powershell</tags>
15+
<summary>Chocolatey CLI's PowerShell helper commands</summary>
16+
<description>
17+
Chocolatey is a package manager for Windows (like apt-get but for Windows).
18+
19+
This is the Chocolatey PowerShell Library (API / DLL) package which contains the PowerShell helper commands used in Chocolatey CLI itself.
20+
21+
### Information
22+
23+
- [Chocolatey Website and Community Package Repository](https://community.chocolatey.org)
24+
- [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)
25+
- [Twitter](https://twitter.com/chocolateynuget) / [Facebook](https://www.facebook.com/ChocolateySoftware) / [GitHub](https://github.com/chocolatey)
26+
- [Blog](https://blog.chocolatey.org/) / [Newsletter](https://chocolatey.us8.list-manage1.com/subscribe?u=86a6d80146a0da7f2223712e4&amp;id=73b018498d)
27+
- [Documentation](https://docs.chocolatey.org/en-us/) / [Support](https://chocolatey.org/support)
28+
</description>
29+
<releaseNotes>
30+
See all - https://docs.chocolatey.org/en-us/choco/release-notes
31+
</releaseNotes>
32+
</metadata>
33+
</package>

‎recipe.cake‎

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ Func<List<ILMergeConfig>> getILMergeConfigs = () =>
1515
var targetPlatform = "v4,C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.8";
1616
var assembliesToILMerge = GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/*.{exe|dll}")
1717
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/choco.exe")
18-
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/System.Management.Automation.dll");
18+
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/System.Management.Automation.dll")
19+
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco/Chocolatey.PowerShell.dll");
1920

2021
Information("The following assemblies have been selected to be ILMerged for choco.exe...");
2122
foreach (var assemblyToILMerge in assembliesToILMerge)
@@ -34,10 +35,11 @@ Func<List<ILMergeConfig>> getILMergeConfigs = () =>
3435
AssemblyPaths = assembliesToILMerge });
3536

3637
assembliesToILMerge = GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/*.{exe|dll}")
37-
- GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/choco.exe")
38-
- GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/chocolatey.dll")
39-
- GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/log4net.dll")
40-
- GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/System.Management.Automation.dll");
38+
- GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/choco.exe")
39+
- GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/chocolatey.dll")
40+
- GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/log4net.dll")
41+
- GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/System.Management.Automation.dll")
42+
- GetFiles(BuildParameters.Paths.Directories.PublishedLibraries + "/chocolatey/Chocolatey.PowerShell.dll");
4143

4244
Information("The following assemblies have been selected to be ILMerged for chocolatey.dll...");
4345
foreach (var assemblyToILMerge in assembliesToILMerge)
@@ -58,10 +60,11 @@ Func<List<ILMergeConfig>> getILMergeConfigs = () =>
5860
if (DirectoryExists(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/"))
5961
{
6062
var no7zAssembliesToILMerge = GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/*.{exe|dll}")
61-
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/choco.exe")
62-
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/System.Management.Automation.dll")
63-
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/chocolatey.tests*.dll")
64-
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/{Moq|nunit|Should|testcentric}*.dll");
63+
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/choco.exe")
64+
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/System.Management.Automation.dll")
65+
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/chocolatey.tests*.dll")
66+
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/{Moq|nunit|Should|testcentric}*.dll")
67+
- GetFiles(BuildParameters.Paths.Directories.PublishedApplications + "/choco-no7zip/Chocolatey.PowerShell.dll");
6568

6669
Information("The following assemblies have been selected to be ILMerged for choco.exe No7zip Version...");
6770
foreach (var assemblyToILMerge in no7zAssembliesToILMerge)
@@ -121,13 +124,15 @@ Func<FilePathCollection> getFilesToSign = () =>
121124
var filesToSign = GetFiles(BuildParameters.Paths.Directories.NuGetNuspecDirectory + "/lib/chocolatey.dll")
122125
+ GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/choco.exe")
123126
+ GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/tools/{checksum|shimgen}.exe")
124-
+ GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/redirects/*.exe");
127+
+ GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/redirects/*.exe")
128+
+ GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll");
125129

126130
if (DirectoryExists(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip"))
127131
{
128132
filesToSign += GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/choco.exe")
129133
+ GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/tools/{checksum|shimgen}.exe")
130-
+ GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/redirects/*.exe");
134+
+ GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/redirects/*.exe")
135+
+ GetFiles(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "-no7zip/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll");
131136
}
132137

133138
Information("The following assemblies have been selected to be signed...");
@@ -172,6 +177,10 @@ Task("Prepare-Chocolatey-Packages")
172177

173178
StartProcess(BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/choco.exe", new ProcessSettings{ Arguments = "unpackself -f -y --allow-unofficial-build --run-actual" });
174179

180+
// Copy Chocolatey.PowerShell.dll and its help.xml file
181+
CopyFile(BuildParameters.Paths.Directories.PublishedLibraries + "/Chocolatey.PowerShell/Chocolatey.PowerShell.dll", BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll");
182+
CopyFile(BuildParameters.Paths.Directories.PublishedLibraries + "/Chocolatey.PowerShell/Chocolatey.PowerShell.dll-help.xml", BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll-help.xml");
183+
175184
// Tidy up logs and config folder which are not required
176185
var logsDirectory = BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/logs";
177186
var configDirectory = BuildParameters.Paths.Directories.ChocolateyNuspecDirectory + "/tools/chocolateyInstall/config";
@@ -260,6 +269,10 @@ Task("Prepare-ChocolateyNo7zip-Package")
260269

261270
StartProcess(nuspecDirectory + "/tools/chocolateyInstall/choco.exe", new ProcessSettings{ Arguments = "unpackself -f -y --allow-unofficial-build" });
262271

272+
// Copy Chocolatey.PowerShell.dll and help.xml file
273+
CopyFile(BuildParameters.Paths.Directories.PublishedLibraries + "/Chocolatey.PowerShell/Chocolatey.PowerShell.dll", nuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll");
274+
CopyFile(BuildParameters.Paths.Directories.PublishedLibraries + "/Chocolatey.PowerShell/Chocolatey.PowerShell.dll-help.xml", nuspecDirectory + "/tools/chocolateyInstall/helpers/Chocolatey.PowerShell.dll-help.xml");
275+
263276
// Tidy up logs and config folder which are not required
264277
var logsDirectory = nuspecDirectory + "/tools/chocolateyInstall/logs";
265278
var configDirectory = nuspecDirectory + "/tools/chocolateyInstall/config";

0 commit comments

Comments
 (0)