Better edge case handling, documentation

Azure · Aug 30, 2023 · 7276670 · 7276670
1 parent a29c0ba
commit 7276670
Showing 1 changed file with 75 additions and 37 deletions.
diff --git a/eng/common/scripts/Update-DocsMsPackageMonikers.ps1 b/eng/common/scripts/Update-DocsMsPackageMonikers.ps1
@@ -1,3 +1,16 @@
+<#
+.SYNOPSIS
+Move metadata JSON and package-level overview markdown files for deprecated packages to the legacy folder.
+
+.DESCRIPTION
+Move onboarding information to the "legacy" moniker for whose support is "deprecated" in the Metadata CSV.
+Only one version of a package can be documented in the "legacy" moniker. If multiple versions are available,
+the "latest" version will be used and the "preview" version will be deleted.
+
+.PARAMETER DocRepoLocation
+The location of the target docs repository.
+#>
+
 param(
     [Parameter(Mandatory = $true)]
     [string] $DocRepoLocation
@@ -24,62 +37,87 @@ function getPackageMetadata($moniker) {
     return $metadata
 }
 
-function getPackageMetadataFileLocation($packageIdentity, $lookupTable) { 
-    if ($lookupTable.ContainsKey($packageIdentity)) { 
-        return $lookupTable[$packageIdentity]['File']
+function getPackageInfoFromLookup($packageIdentity, $version, $lookupTable) { 
+    if ($lookupTable.ContainsKey($packageIdentity)) {
+        if ($lookupTable[$packageIdentity]['Metadata'].Version -eq $version) {
+            # Only return if the version matches
+            return $lookupTable[$packageIdentity]
+        }
     }
 
     return $null 
 }
 
+function moveToLegacy($packageInfo) { 
+    $docsMsMetadata = &$GetDocsMsMetadataForPackageFn -PackageInfo $packageInfo['Metadata']
+
+    Write-Host "Move to legacy: $($packageInfo['Metadata'].Name)"
+    $packageInfoPath = $packageInfo['File']
+    Move-Item "$($packageInfoPath.Directory)/$($packageInfoPath.BaseName).*" "$DocRepoLocation/metadata/legacy/" -Force
+
+    $readmePath = "$DocRepoLocation/$($docsMsMetadata.PreviewReadMeLocation)/$($docsMsMetadata.DocsMsReadMeName)-readme.md"
+    if (Test-Path $readmePath) {
+        Move-Item `
+            $readmePath `
+            "$DocRepoLocation/$($docsMsMetadata.LegacyReadMeLocation)/" `
+            -Force
+    }
+}
+
+function deletePackageInfo($packageInfo) { 
+    $docsMsMetadata = &$GetDocsMsMetadataForPackageFn -PackageInfo $packageInfo['Metadata']
+
+    Write-Host "Delete superseded package: $($packageInfo['Metadata'].Name)"
+    $packageInfoPath = $packageInfo['File']
+    Remove-Item "$($packageInfoPath.Directory)/$($packageInfoPath.BaseName).*" -Force
+
+    $readmePath = "$DocRepoLocation/$($docsMsMetadata.PreviewReadMeLocation)/$($docsMsMetadata.DocsMsReadMeName)-readme.md"
+    if (Test-Path $readmePath) {
+        Remove-Item $readmePath -Force
+    }
+}
+
 $metadataLookup = @{ 
-    'latest' = getPackageMetadata 'latest'
+    'latest'  = getPackageMetadata 'latest'
     'preview' = getPackageMetadata 'preview'
-    'legacy' = getPackageMetadata 'legacy'
 }
 $deprecatedPackages = (Get-CSVMetadata).Where({ $_.Support -eq 'deprecated' })
 
 foreach ($package in $deprecatedPackages) {
     $packageIdentity = $package.Package
-    # TODO: Ensure this works
+    # TODO: Ensure this works in Java
     if (Test-Path "Function:$GetPackageIdentity") {
         $packageIdentity = &$GetPackageIdentity $package
     }
 
-    $previewMetadataPath = getPackageMetadataFileLocation `
-        -packageIdentity $packageIdentity `
-        -lookupTable $metadataLookup['preview']
-
-    if ($previewMetadataPath) {
-        $metadata = &$GetDocsMsMetadataForPackageFn -PackageInfo $metadataLookup['preview'][$packageIdentity]['Metadata']
-
-        Write-Host "Package $packageIdentity is deprecated but has file in preview metadata folder. Moving to legacy."
-        Move-Item $previewMetadataPath "$DocRepoLocation/metadata/legacy/" -Force
-
-
-        if (Test-Path "$DocRepoLocation/$($metadata.PreviewReadMeLocation)/$($metadata.DocsMsReadMeName)-readme.md") {
-            Move-Item `
-                "$DocRepoLocation/$($metadata.PreviewReadMeLocation)/$($metadata.DocsMsReadMeName)-readme.md" `
-                "$DocRepoLocation/$($metadata.LegacyReadMeLocation)/" `
-                -Force
-        }
-
+    $packageInfoPreview = $packageInfoLatest = $null
+    if ($package.VersionPreview) {
+        $packageInfoPreview = getPackageInfoFromLookup `
+            -packageIdentity $packageIdentity `
+            -version $package.VersionPreview `
+            -lookupTable $metadataLookup['preview']
     }
 
-    $latestMetadataPath = getPackageMetadataFileLocation `
-        -packageIdentity $packageIdentity `
-        -lookupTable $metadataLookup['latest']
+    if ($package.VersionGA) { 
+        $packageInfoLatest = getPackageInfoFromLookup `
+            -packageIdentity $packageIdentity `
+            -version $package.VersionGA `
+            -lookupTable $metadataLookup['latest']
+    }
 
-    if ($latestMetadataPath) {
-        $metadata = &$GetDocsMsMetadataForPackageFn -PackageInfo $metadataLookup['latest'][$packageIdentity]['Metadata']
+    if (!$packageInfoPreview -and !$packageInfoLatest) {
+        # Nothing to move or delete
+        continue
+    }
 
-        Write-Host "Package $packageIdentity is deprecated but has file in latest metadata folder. Moving to legacy. (might overwrite preview version if it exists in metadata/legacy)"
-        Move-Item $latestMetadataPath "$DocRepoLocation/metadata/legacy/" -Force
-        if (Test-Path  "$DocRepoLocation/$($metadata.LatestReadMeLocation)/$($metadata.DocsMsReadMeName)-readme.md") {
-            Move-Item `
-                "$DocRepoLocation/$($metadata.LatestReadMeLocation)/$($metadata.DocsMsReadMeName)-readme.md" `
-                "$DocRepoLocation/$($metadata.LegacyReadMeLocation)/" `
-                -Force
-        }
+    if ($packageInfoPreview -and $packageInfoLatest) {
+        # Delete metadata JSON and package-level overview markdown files for
+        # the preview version instead of moving both. This mitigates situations
+        # where the "latest" verison doesn't have a package-level overview 
+        # markdown file and the "preview" version does.
+        deletePackageInfo $packageInfoPreview
+        moveToLegacy $packageInfoLatest
+    } else {
+        moveToLegacy ($packageInfoPreview ?? $packageInfoLatest)
     }
 }