Skip to content

Commit 007deb7

Browse files
Fix issues with Build-Wiki and add Wiki documentation to CONTRIBUTING.md's Release section (#311)
Fixed some issues with `Build-Wiki`: * Ensured that `Home.md` is not incorrectly categorized as deprecated. * Fixed how we check for `platyPS` being installed. * Fixed how we reference files in `Move-Item` to solve the issue when the file being moved is new. * Added warning/reminder to run this under `PS7+` to avoid issue with how multi-line examples get formatted. Also added Wiki updating instructions to the release section of `CONTRIBUTING.md`.
1 parent a1640a2 commit 007deb7

File tree

2 files changed

+45
-3
lines changed

2 files changed

+45
-3
lines changed

CONTRIBUTING.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ Looking for information on how to use this module? Head on over to [README.md](
3737
* [Updating the CHANGELOG](#updating-the-changelog)
3838
* [Adding a New Tag](#adding-a-new-tag)
3939
* [Running the Release Build](#running-the-release-build)
40+
* [Updating the Wiki documentation](#updating-the-wiki-documentation)
4041
* [Contributors](#contributors)
4142
* [Legal and Licensing](#legal-and-licensing)
4243

@@ -551,6 +552,41 @@ maintainer because it accesses internal services to sign the module files with M
551552
> Instructions for updating the `PowerShellGalleryApiKey` secret in the pipeline can be found in the
552553
> [internal Microsoft repo for this project](https://microsoft.visualstudio.com/Apps/_git/eng.powershellforgithub).
553554
555+
#### Updating the Wiki Documentation
556+
557+
The [Wiki](https://github.com/microsoft/PowerShellForGitHub/wiki) contains the full documentation
558+
for all exported commands from the module, thanks to [platyPS](https://github.com/PowerShell/platyPS).
559+
560+
Every time a new release occurs, the Wiki should be updated to reflect any changes that occurred
561+
within the module.
562+
563+
1. Ensure that you have cloned the Wiki:
564+
565+
```
566+
git clone https://github.com/microsoft/PowerShellForGitHub.wiki.git
567+
```
568+
569+
2. Open a PowerShell 7+ console window (don't use Windows PowerShell as there's a platyPS bug
570+
with that version regarding multi-line examples) and navigate to your Wiki clone.
571+
572+
3. Run this command (assuming that you have a `PowerShellForGitHub` clone at the same level as your
573+
Wiki clone):
574+
575+
```powershell
576+
..\PowerShellForGitHub\build\scripts\Build-Wiki.ps1 -Path .\ -RemoveDeprecated -Verbose -Force
577+
```
578+
579+
4. Verify the changes all make sense. You will also need to manually copy the core content of
580+
`PowerShellForGitHub.md` into `Home.md`. For the time being, we are duplicating that content
581+
in Home until such time as we have better content to put there.
582+
583+
5. Commit the change and directly push it to the Wiki's `master` branch...no need to go through
584+
a pull request for the Wiki changes.
585+
586+
> This is not currently automated as part of the [Release pipeline](#running-the-release-build)
587+
> because I don't currently want to store any credentials/tokens with write access to the repo
588+
> in the pipeline.
589+
554590
----------
555591

556592
### Contributors

build/scripts/Build-Wiki.ps1

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -344,6 +344,11 @@ Set-StrictMode -Version 1.0
344344

345345
$Path = Resolve-Path -Path $Path
346346

347+
if ($PSVersionTable.PSVersion.Major -lt 7)
348+
{
349+
Write-Warning 'It is recommended to run this with PowerShell 7+, as platyPS has a bug which doesn''t properly handle multi-line examples when run on older vesrions of PowerShell.'
350+
}
351+
347352
$numSteps = 11
348353
$currentStep = 0
349354
$progressParams = @{
@@ -354,7 +359,7 @@ $progressParams = @{
354359
#######
355360
$currentStep++
356361
Write-Progress @progressParams -Status 'Ensuring PlatyPS installed' -PercentComplete (($currentStep / $numSteps) * 100)
357-
if ($null -eq (Get-Module -Name 'PlatyPS'))
362+
if ($null -eq (Get-Module -Name 'PlatyPS' -ListAvailable))
358363
{
359364
Write-Verbose -Message 'Installing PlatyPS Module'
360365
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Scope CurrentUser -Force -Verbose:$false | Out-Null
@@ -377,6 +382,7 @@ $moduleRootPageFileName = "$ModuleName.md"
377382
# files that should be _removed_ from the Wiki due to rename/removal of exports.
378383
$tempFolder = Join-Path -Path $env:TEMP -ChildPath ([Guid]::NewGuid().Guid)
379384
New-Item -Path $tempFolder -ItemType Directory | Out-Null
385+
Write-Verbose -Message "Working from temp location: $tempFolder"
380386

381387
#######
382388
$currentStep++
@@ -475,7 +481,7 @@ foreach ($file in $currentFiles)
475481
$content = Get-Content -Path $file -Raw -Encoding utf8
476482
if (($content -match $generatedMarker) -and
477483
($file.BaseName -notin $modulePages) -and
478-
($file.Name -ne $moduleRootPageFileName))
484+
($file.Name -notin ($moduleRootPageFileName, 'Home.md')))
479485
{
480486
$deprecatedFiles += $file
481487
}
@@ -508,7 +514,7 @@ Write-Progress @progressParams -Status "Moving generated content to final destin
508514
$files = Get-ChildItem -Path $tempFolder
509515
foreach ($file in $files)
510516
{
511-
Move-Item -Path $file -Destination $Path -Force:$Force.IsPresent
517+
Move-Item -Path $file.FullName -Destination $Path -Force:$Force.IsPresent
512518
}
513519

514520
Remove-Item -Path $tempFolder -Recurse -Force

0 commit comments

Comments
 (0)