diff --git a/.vsts-ci.yml b/.vsts-ci.yml index 02d8fc3..d4844cc 100644 --- a/.vsts-ci.yml +++ b/.vsts-ci.yml @@ -26,6 +26,8 @@ resources: extends: template: azure-pipelines/MicroBuild.1ES.Official.yml@MicroBuildTemplate parameters: + settings: + networkIsolationPolicy: Permissive,CFSClean,CFSClean2 pool: name: VSEngSS-MicroBuild2022-1ES sdl: diff --git a/.vsts-compliance.yml b/.vsts-compliance.yml index e093f96..9049ea4 100644 --- a/.vsts-compliance.yml +++ b/.vsts-compliance.yml @@ -39,6 +39,8 @@ resources: extends: template: azure-pipelines/MicroBuild.1ES.Unofficial.yml@MicroBuildTemplate parameters: + settings: + networkIsolationPolicy: Permissive,CFSClean,CFSClean2 pool: name: VSEngSS-MicroBuild2022-1ES sdl: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 875fa48..57feeec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,15 @@ Code analysis and style cop rules are defined for this solution, but are current If you add any commands please update the `Tags` property of the _VSSetup.nuproj_ project as appropriate. This project is used instead of `Publish-Module` from the _PowerShellGet_ module because it works better with the build systems and can be tested on developer machines without also publishing. +## Documentation + +Cmdlet and `about_` help is authored as markdown under _docs\VSSetup_ and compiled into the checked-in help artifacts under _src\VSSetup.PowerShell\help_. If you change any markdown under _docs\VSSetup_, regenerate these artifacts and check the updated output files in as part of the same pull request: + +```powershell +Install-Module -Name platyPS -Scope CurrentUser -Force +build\Update-Help.ps1 +``` + ## Building Before you can build this project from the command line with MSBuild or within Visual Studio, you must restore packages including the [embeddable interop types][interop]. diff --git a/NuGet.config b/NuGet.config new file mode 100644 index 0000000..15194fc --- /dev/null +++ b/NuGet.config @@ -0,0 +1,7 @@ + + + + + + + diff --git a/build/Update-Help.ps1 b/build/Update-Help.ps1 new file mode 100644 index 0000000..bdf65a9 --- /dev/null +++ b/build/Update-Help.ps1 @@ -0,0 +1,40 @@ +<# +.SYNOPSIS + Regenerates the checked-in PowerShell help artifacts from the markdown docs. + +.DESCRIPTION + The official build runs under 1ES network isolation and cannot reach the + PowerShell Gallery, so it no longer installs platyPS or runs New-ExternalHelp. + Instead, the generated help artifacts are checked in under + src\VSSetup.PowerShell\help and copied to the build output by the project. + + Run this script locally (outside the isolated build) whenever the cmdlet or + about_ markdown files under docs\VSSetup change, then commit the regenerated + files under src\VSSetup.PowerShell\help. + +.NOTES + Requires the platyPS module. Install it locally with: + Install-Module -Name platyPS -Scope CurrentUser -Force +#> +[CmdletBinding()] +param() + +$ErrorActionPreference = 'Stop' + +$repoRoot = Split-Path -Parent $PSScriptRoot +$docsPath = Join-Path $repoRoot 'docs\VSSetup' +$outputPath = Join-Path $repoRoot 'src\VSSetup.PowerShell\help' + +if (-not (Get-Module -ListAvailable -Name platyPS)) { + throw "platyPS is not installed. Run: Install-Module -Name platyPS -Scope CurrentUser -Force" +} + +Import-Module platyPS + +if (-not (Test-Path -Path $outputPath)) { + $null = New-Item -Path $outputPath -ItemType Directory +} + +New-ExternalHelp -Path $docsPath -OutputPath $outputPath -Force | Out-Null + +Write-Host "Regenerated help artifacts in $outputPath. Review and commit the changes." diff --git a/build/build.yml b/build/build.yml index ee9bad4..fa98e24 100644 --- a/build/build.yml +++ b/build/build.yml @@ -10,8 +10,12 @@ parameters: DockerProjectName: microsoft-vssetup-powershell steps: +- task: NuGetAuthenticate@1 + displayName: Authenticate to Azure Artifacts + - pwsh: | - dotnet tool install --tool-path "${env:AGENT_TOOLSDIRECTORY}\nbgv" nbgv + dotnet tool install --tool-path "${env:AGENT_TOOLSDIRECTORY}\nbgv" ` + --configfile "$(Build.SourcesDirectory)\NuGet.config" nbgv $version = & "${env:AGENT_TOOLSDIRECTORY}\nbgv\nbgv.exe" get-version --variable SemVer1 & "${env:AGENT_TOOLSDIRECTORY}\nbgv\nbgv.exe" cloud --version $version displayName: Set cloud build version @@ -21,17 +25,9 @@ steps: - task: NuGetCommand@2 displayName: Restore nuget packages - -- pwsh: | - Install-Module -Name platyPS -Repository PSGallery -SkipPublisherCheck -Force - displayName: Install PowerShell modules - -- pwsh: | - New-ExternalHelp -Path docs\VSSetup -OutputPath "src\VSSetup.PowerShell\bin\${env:CONFIGURATION}" -Force - displayName: Compile documentation - env: - CONFIGURATION: ${{ parameters.BuildConfiguration }} - workingDirectory: $(Build.SourcesDirectory) + inputs: + feedsToUse: config + nugetConfigPath: $(Build.SourcesDirectory)\NuGet.config - task: VSBuild@1 displayName: Build solution @@ -115,6 +111,8 @@ steps: displayName: Restore nuget packages inputs: restoreSolution: $(Build.SourcesDirectory)\pkg\VSSetup\VSSetup.signproj + feedsToUse: config + nugetConfigPath: $(Build.SourcesDirectory)\NuGet.config - task: VSBuild@1 displayName: Sign packages diff --git a/src/VSSetup.PowerShell/VSSetup.PowerShell.csproj b/src/VSSetup.PowerShell/VSSetup.PowerShell.csproj index c248cec..771fe40 100644 --- a/src/VSSetup.PowerShell/VSSetup.PowerShell.csproj +++ b/src/VSSetup.PowerShell/VSSetup.PowerShell.csproj @@ -36,6 +36,14 @@ PreserveNewest + + %(Filename)%(Extension) + PreserveNewest + + + %(Filename)%(Extension) + PreserveNewest +