Skip to content

Commit 2611bb6

Browse files
authored
Validate docs using the REX tool (#27935)
Fixes #25684 * Removes docker container * Updates relevant scripts and removes old code paths * Adds job to upgrade the REX tool if tests pass Example runs: * Successful run of daily pipeline: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=3298420&view=logs&j=f8e040b3-c0ff-5789-0eda-99daaaa3fc1b&t=7702a9c8-4b61-5cd3-c28d-9b1cea81bf7e * Successful SDK package release: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=3302248&view=logs&j=19b87903-f8bc-5cbb-22d9-4f6eb3469d8e&t=39d7f548-7a77-5d57-b2f3-bf0cc5f8dda2&l=150 * Successful docindex run: * pipeline run: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=3298899&view=logs&j=dc056dfc-c0cf-5958-c8c4-8da4f91a3739&t=dc056dfc-c0cf-5958-c8c4-8da4f91a3739 * diff showing package upgrades did not change (may show drift as packages release, focus on `ci-configs/packages-*.json`): https://github.com/MicrosoftDocs/azure-docs-sdk-node/compare/djurek/rex-tests?expand=1 * Tool upgrade: * No new version: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=3298685&view=logs&j=f0b9ce84-b5fb-5cd2-d7e4-8e2b722448a2&t=95e002a9-090a-5230-9ea9-b23402ed153e * New version test and upgrade: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=3298739&view=logs&j=f0b9ce84-b5fb-5cd2-d7e4-8e2b722448a2&t=95e002a9-090a-5230-9ea9-b23402ed153e * PR: #27917 * New version test fails: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=3298727&view=logs&j=f0b9ce84-b5fb-5cd2-d7e4-8e2b722448a2&t=95e002a9-090a-5230-9ea9-b23402ed153e
1 parent be35095 commit 2611bb6

File tree

8 files changed

+134
-188
lines changed

8 files changed

+134
-188
lines changed

eng/pipelines/docindex.yml

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,33 @@ variables:
44
jobs:
55
- template: /eng/common/pipelines/templates/jobs/docindex.yml
66

7+
- job: UpgradeRexTool
8+
timeoutInMinutes: 10
9+
pool:
10+
vmImage: ubuntu-22.04
11+
12+
steps:
13+
- template: /eng/common/pipelines/templates/steps/sparse-checkout.yml
14+
parameters:
15+
SkipCheckoutNone: true
16+
17+
- task: Powershell@2
18+
inputs:
19+
pwsh: true
20+
filePath: eng/scripts/docs/Update-RexValidationTool.ps1
21+
displayName: Update JS REX Validation Tool
22+
23+
- template: /eng/common/pipelines/templates/steps/create-pull-request.yml
24+
parameters:
25+
PRBranchName: docs/rex-tool-upgrade
26+
# Force push as this task updates a single file and history is not
27+
# necessary for changes in this branch.
28+
PushArgs: -f
29+
PRTitle: Upgrade JS REX Validation Tool
30+
PRBody: |
31+
This PR upgrades the JS REX Validation Tool to the latest version.
32+
Testing was done in $(System.CollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)
33+
734
- job: UpdateDocsMsBuildConfig
835
timeoutInMinutes: 90
936
pool:
@@ -12,7 +39,6 @@ jobs:
1239
DocRepoLocation: $(Pipeline.Workspace)/docs
1340
DocRepoOwner: MicrosoftDocs
1441
DocRepoName: azure-docs-sdk-node
15-
DocValidationImageId: azuresdkimages.azurecr.io/jsrefautocr:latest
1642
steps:
1743
# Sync docs repo (this can be sparse)
1844
- template: /eng/common/pipelines/templates/steps/sparse-checkout.yml
@@ -26,12 +52,8 @@ jobs:
2652
Repositories:
2753
- Name: $(DocRepoOwner)/$(DocRepoName)
2854
WorkingDirectory: $(DocRepoLocation)
29-
# Pull and build the docker image.
30-
- template: /eng/common/pipelines/templates/steps/docker-pull-image.yml
31-
parameters:
32-
ContainerRegistryClientId: $(azuresdkimages-cr-clientid)
33-
ContainerRegistryClientSecret: $(azuresdkimages-cr-clientsecret)
34-
ImageId: "$(DocValidationImageId)"
55+
56+
- template: /eng/pipelines/templates/steps/install-rex-validation-tool.yml
3557

3658
- task: Powershell@2
3759
inputs:
@@ -45,7 +67,7 @@ jobs:
4567
inputs:
4668
pwsh: true
4769
filePath: eng/common/scripts/Update-DocsMsPackages.ps1
48-
arguments: -DocRepoLocation $(DocRepoLocation) -ImageId '$(DocValidationImageId)'
70+
arguments: -DocRepoLocation $(DocRepoLocation)
4971
displayName: Update Docs Onboarding for main branch
5072
condition: and(succeeded(), or(eq(variables['Build.Reason'], 'Schedule'), eq(variables['Force.MainUpdate'], 'true')))
5173

@@ -73,7 +95,7 @@ jobs:
7395
filePath: eng/common/scripts/Verify-RequiredDocsJsonMembers.ps1
7496
arguments: >-
7597
-DocRepoLocation $(DocRepoLocation)
76-
displayName: Verify Required Docs Json Members
98+
displayName: Verify Required Docs Json Members
7799

78100
# Push changes to docs repo
79101
- template: /eng/common/pipelines/templates/steps/set-default-branch.yml
@@ -84,7 +106,7 @@ jobs:
84106
parameters:
85107
BaseRepoBranch: $(DefaultBranch)
86108
BaseRepoOwner: $(DocRepoOwner)
87-
CommitMsg: "Update docs CI configuration"
109+
CommitMsg: "Update docs CI configuration Build: $(System.CollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"
88110
TargetRepoName: $(DocRepoName)
89111
TargetRepoOwner: $(DocRepoOwner)
90112
WorkingDirectory: $(DocRepoLocation)

eng/pipelines/templates/stages/archetype-js-release.yml

Lines changed: 7 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,6 @@ stages:
119119
name: azsdk-pool-mms-ubuntu-2004-general
120120
vmImage: MMSUbuntu20.04
121121

122-
variables:
123-
DocValidationImageId: azuresdkimages.azurecr.io/jsrefautocr:latest
124122
strategy:
125123
runOnce:
126124
deploy:
@@ -131,12 +129,9 @@ stages:
131129
- sdk/**/*.md
132130
- .github/CODEOWNERS
133131
- download: current
134-
# Pull and build the docker image.
135-
- template: /eng/common/pipelines/templates/steps/docker-pull-image.yml
136-
parameters:
137-
ContainerRegistryClientId: $(azuresdkimages-cr-clientid)
138-
ContainerRegistryClientSecret: $(azuresdkimages-cr-clientsecret)
139-
ImageId: "$(DocValidationImageId)"
132+
133+
- template: /eng/pipelines/templates/steps/install-rex-validation-tool.yml
134+
140135
- template: /eng/common/pipelines/templates/steps/update-docsms-metadata.yml
141136
parameters:
142137
PackageInfoLocations:
@@ -151,7 +146,6 @@ stages:
151146
- metadata/
152147
- ci-configs/packages-latest.json
153148
- ci-configs/packages-preview.json
154-
DocValidationImageId: "$(DocValidationImageId)"
155149

156150
- ${{if ne(artifact.skipPublishDocGithubIo, 'true')}}:
157151
- deployment: PublishDocsGitHubIO
@@ -285,8 +279,7 @@ stages:
285279
pool:
286280
name: azsdk-pool-mms-ubuntu-2004-general
287281
vmImage: MMSUbuntu20.04
288-
variables:
289-
DocValidationImageId: azuresdkimages.azurecr.io/jsrefautocr:latest
282+
290283
steps:
291284
- template: /eng/common/pipelines/templates/steps/sparse-checkout.yml
292285
parameters:
@@ -297,12 +290,9 @@ stages:
297290
- pwsh: |
298291
Get-ChildItem -Recurse $(Pipeline.Workspace)/${{parameters.ArtifactName}}/
299292
displayName: Show visible artifacts
300-
# Pull and build the docker image.
301-
- template: /eng/common/pipelines/templates/steps/docker-pull-image.yml
302-
parameters:
303-
ContainerRegistryClientId: $(azuresdkimages-cr-clientid)
304-
ContainerRegistryClientSecret: $(azuresdkimages-cr-clientsecret)
305-
ImageId: "$(DocValidationImageId)"
293+
294+
- template: /eng/pipelines/templates/steps/install-rex-validation-tool.yml
295+
306296
- template: /eng/common/pipelines/templates/steps/update-docsms-metadata.yml
307297
parameters:
308298
PackageInfoLocations:
@@ -320,6 +310,5 @@ stages:
320310
- metadata/
321311
- ci-configs/packages-latest.json
322312
- ci-configs/packages-preview.json
323-
DocValidationImageId: "$(DocValidationImageId)"
324313

325314
- template: /eng/common/pipelines/templates/steps/docsms-ensure-validation.yml
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
steps:
2+
- pwsh: |
3+
npm install -g "@microsoft/type2docfx@$(Get-Content eng/scripts/docs/type2docfx.version.txt)"
4+
displayName: Install @microsoft/type2docfx for package validation

eng/scripts/Language-Settings.ps1

Lines changed: 12 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -217,41 +217,6 @@ function Get-DocsMsPackageName($packageName, $packageVersion) {
217217
return "$(Get-PackageNameFromDocsMsConfig $packageName)@$packageVersion"
218218
}
219219

220-
221-
# Performs package validation for a list of packages provided in the doc
222-
# onboarding format ("name" is the only required field):
223-
# @{
224-
# name = "@azure/attestation@dev";
225-
# folder = "./types";
226-
# registry = "<url>";
227-
# ...
228-
# }
229-
function ValidatePackagesForDocs($packages, $DocValidationImageId) {
230-
# Using GetTempPath because it works on linux and windows
231-
$tempDirectory = Join-Path ([System.IO.Path]::GetTempPath()) ([System.IO.Path]::GetRandomFileName())
232-
New-Item -ItemType Directory -Force -Path $tempDirectory | Out-Null
233-
234-
$scriptRoot = $PSScriptRoot
235-
# Run this in parallel as each step takes a long time to run
236-
$validationOutput = $packages | ForEach-Object { [PSCustomObject]$_ } | Foreach-Object -Parallel {
237-
# Get value for variables outside of the Foreach-Object scope
238-
$scriptRoot = "$using:scriptRoot"
239-
$workingDirectory = "$using:tempDirectory"
240-
Write-Host "`"$scriptRoot\validate-docs-package.ps1`" -Package $_ -DocValidationImageId `"$($using:DocValidationImageId)`" -WorkingDirectory $workingDirectory"
241-
return ."$scriptRoot\validate-docs-package.ps1" -Package $_ -DocValidationImageId "$using:DocValidationImageId" -WorkingDirectory $workingDirectory
242-
}
243-
244-
# Clean up temp folder
245-
Remove-Item -Path $tempDirectory -Force -Recurse -ErrorAction Ignore | Out-Null
246-
247-
return $validationOutput
248-
}
249-
250-
$PackageExclusions = @{
251-
'@azure/identity-vscode' = 'Fails type2docfx execution https://github.com/Azure/azure-sdk-for-js/issues/16303';
252-
'@azure/identity-cache-persistence' = 'Fails typedoc2fx execution https://github.com/Azure/azure-sdk-for-js/issues/16310';
253-
}
254-
255220
function Update-javascript-DocsMsPackages($DocsRepoLocation, $DocsMetadata, $DocValidationImageId) {
256221
Write-Host "Excluded packages:"
257222
foreach ($excludedPackage in $PackageExclusions.Keys) {
@@ -454,49 +419,26 @@ function GetExistingPackageVersions ($PackageName, $GroupId = $null) {
454419

455420
# Defined in common.ps1 as:
456421
# $ValidateDocsMsPackagesFn = "Validate-${Language}-DocMsPackages"
457-
function Validate-javascript-DocMsPackages ($PackageInfo, $PackageInfos, $DocRepoLocation, $DocValidationImageId) {
422+
function Validate-javascript-DocMsPackages ($PackageInfo, $PackageInfos, $DocRepoLocation, $DocValidationImageId) {
458423
if (!$PackageInfos) {
459424
$PackageInfos = @($PackageInfo)
460425
}
461426

462-
$outputPackages = @()
427+
$allSucceeded = $true
463428

464429
foreach ($packageInfo in $PackageInfos) {
465-
$fileLocation = ""
466-
if ($packageInfo.DevVersion -or $packageInfo.Version -contains "beta") {
467-
$fileLocation = (Join-Path $DocRepoLocation 'ci-configs/packages-preview.json')
468-
if ($packageInfo.DevVersion) {
469-
$packageInfo.Version = $packageInfo.DevVersion
470-
}
471-
}
472-
else {
473-
$fileLocation = (Join-Path $DocRepoLocation 'ci-configs/packages-latest.json')
474-
}
475-
476-
$packageConfig = Get-Content $fileLocation -Raw | ConvertFrom-Json
430+
$outputLocation = New-Item `
431+
-ItemType Directory `
432+
-Path (Join-Path ([System.IO.Path]::GetTempPath()) ([System.IO.Path]::GetRandomFileName()))
477433

478-
$outputPackage = $packageInfo
479-
480-
foreach ($package in $packageConfig.npm_package_sources) {
481-
if ($package.name -eq $packageInfo.Name) {
482-
$outputPackage = $package
483-
$outputPackage.name = Get-DocsMsPackageName $package.name $packageInfo.Version
484-
break
485-
}
486-
}
487-
488-
$outputPackages += $outputPackage
489-
}
490-
491-
$validationResults = ValidatePackagesForDocs `
492-
-packages $outputPackages `
493-
-DocValidationImageId $DocValidationImageId
494-
495-
foreach ($result in $validationResults) {
496-
if (!$result.Success) {
497-
return $false
434+
Write-Host "type2docfx `"$($packageInfo.Name)@$($packageInfo.Version)`" $outputLocation"
435+
$output = & type2docfx "$($packageInfo.Name)@$($packageInfo.Version)" $outputLocation 2>&1
436+
if ($LASTEXITCODE) {
437+
$allSucceeded = $false
438+
Write-Host "Package $($packageInfo.Name)@$($packageInfo.Version) failed validation"
439+
$output | Write-Host
498440
}
499441
}
500442

501-
return $true
443+
return $allSucceeded
502444
}
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
param(
2+
$PackageName = '@microsoft/type2docfx',
3+
$CurrentVersion = (Get-Content $PSScriptRoot/type2docfx.version.txt)
4+
)
5+
6+
$packageInfo = npm view $PackageName --json | ConvertFrom-Json -AsHashtable
7+
$latestPackageVersion = $packageInfo['dist-tags']['latest']
8+
9+
if ($latestPackageVersion -eq $CurrentVersion) {
10+
Write-Host "The latest version of $PackageName is already $CurrentVersion. Exiting."
11+
exit 0
12+
}
13+
14+
Write-Host "A new version of $PackageName is available: $latestPackageVersion"
15+
16+
npm install -g "$PackageName@$latestPackageVersion"
17+
18+
if ($LASTEXITCODE) {
19+
Write-Host "Failed to install $PackageName@$latestPackageVersion. Exiting."
20+
exit 1
21+
}
22+
23+
try {
24+
$pesterConfig = New-PesterConfiguration @{
25+
Run = @{
26+
Throw = $true;
27+
Path = "$PSScriptRoot/tests/RexValidation.tests.ps1"
28+
}
29+
}
30+
Invoke-Pester -Configuration $pesterConfig
31+
}
32+
catch {
33+
Write-Host "REX tests failed. Exiting."
34+
Write-Host $_.Exception.Message
35+
Write-Error $_
36+
exit 1
37+
}
38+
39+
Set-Content `
40+
-Path "$PSScriptRoot/type2docfx.version.txt" `
41+
-Value $latestPackageVersion
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
Import-Module Pester
2+
3+
BeforeDiscovery {
4+
$RexToolSpecs = Get-Content "$PSScriptRoot/rex-tool-tests.json" | ConvertFrom-Json -AsHashtable
5+
}
6+
7+
BeforeAll {
8+
. $PSScriptRoot/../../../common/scripts/common.ps1
9+
10+
# Returns a package info object with Name and Version properties
11+
# "@microsoft/[email protected]" -> @{ Name = "@microsoft/sample-package"; Version = "1.2.3" }
12+
# "@microsoft/sample-package" -> @{ Name = "@microsoft/sample-package"; Version = "" }
13+
# "[email protected]" -> @{ Name = "sample-package"; Version = "1.2.3" }
14+
function getPackageInfo($packageName) {
15+
$output = @{ Name = $packageName; Version = '' }
16+
17+
if ($packageName -match '^(?<pkgName>.+?)(@(?<pkgVersion>.+))?$') {
18+
$pkgName = $Matches['pkgName']
19+
$pkgVersion = $Matches['pkgVersion']
20+
$output.Name = $pkgName
21+
$output.Version = $pkgVersion
22+
}
23+
24+
return $output
25+
}
26+
27+
}
28+
29+
Describe "Validate-javascript-DocMsPackages" -Tag "LiveTests" {
30+
It "Package <Package> returns result <ExpectedResult>" -ForEach $RexToolSpecs {
31+
32+
$packageInfo = getPackageInfo($Package)
33+
34+
$output = Validate-javascript-DocMsPackages -PackageInfo $packageInfo
35+
$output | Should -Be $ExpectedResult
36+
}
37+
}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
2.0.8

0 commit comments

Comments
 (0)