Add ReleaseTrackingOnly option to Prepare-Release (Azure#20041)

Co-authored-by: Wes Haggard <[email protected]>

Author: azure-sdk

eng/common/scripts/Helpers/DevOps-WorkItem-Helpers.ps1

@@ -163,21 +163,25 @@ function FindPackageWorkItem($lang, $packageName, $version, $outputCommand = $tr
 
   $workItems = Invoke-AzBoardsCmd "query" $parameters $outputCommand
 
+  if ($workItems -and $workItems.Count -eq 1000) {
+    Write-Warning "Retrieved the max of 1000 items so item list might not be complete."
+  }
+
   foreach ($wi in $workItems)
   {
     $localKey = BuildHashKeyNoNull $wi.fields["Custom.Language"] $wi.fields["Custom.Package"] $wi.fields["Custom.PackageVersionMajorMinor"]
     if (!$localKey) {
       $packageWorkItemWithoutKeyFields[$wi.id] = $wi
       Write-Host "Skipping package [$($wi.id)]$($wi.fields['System.Title']) which is missing required fields language, package, or version."
-      continue 
+      continue
     }
     if ($packageWorkItems.ContainsKey($localKey) -and $packageWorkItems[$localKey].id -ne $wi.id) {
       Write-Warning "Already found package [$($packageWorkItems[$localKey].id)] with key [$localKey], using that one instead of [$($wi.id)]."
     }
     else {
       Write-Verbose "Caching package [$($wi.id)] for [$localKey]"
       $packageWorkItems[$localKey] = $wi
-    } 
+    }
   }
 
   if ($key -and $packageWorkItems.ContainsKey($key)) {
@@ -216,7 +220,7 @@ function UpdateWorkItemParent($childWorkItem, $parentWorkItem, $outputCommand =
 
 function CreateWorkItemParent($id, $parentId, $oldParentId, $outputCommand = $true)
 {
-  # Have to remove old parent first if you want to add a new parent. 
+  # Have to remove old parent first if you want to add a new parent.
   if ($oldParentId)
   {
      $parameters = $ReleaseDevOpsCommonParameters
@@ -287,7 +291,7 @@ function UpdateWorkItem($id, $fields, $title, $state, $assignedTo, $outputComman
 
 function UpdatePackageWorkItemReleaseState($id, $state, $releaseType, $outputCommand = $true)
 {
-  $fields = "`"Custom.ReleaseType=${releaseType}`"" 
+  $fields = "`"Custom.ReleaseType=${releaseType}`""
   return UpdateWorkItem -id $id -state $state -fields $fields -outputCommand $outputCommand
 }
 
@@ -399,10 +403,10 @@ function FindOrCreatePackageGroupParent($serviceName, $packageDisplayName, $outp
   $localKey = BuildHashKey $serviceName $packageDisplayName
   Write-Host "[$($workItem.id)]$localKey - Created Parent"
   $parentWorkItems[$localKey] = $workItem
-  return $workItem 
+  return $workItem
 }
 
-function FindOrCreateServiceParent($serviceName, $outputCommand = $true) 
+function FindOrCreateServiceParent($serviceName, $outputCommand = $true)
 {
   $serviceParent = FindParentWorkItem $serviceName -outputCommand $outputCommand
   if ($serviceParent) {
@@ -733,7 +737,7 @@ function UpdatePackageVersions($pkgWorkItem, $plannedVersions, $shippedVersions)
     {
       $versionSet[$version] = $plannedVersionSet[$version]
     }
-    else 
+    else
     {
       # Looks like we shipped this version so remove it from the planned set
       $plannedVersionSet.Remove($version)
@@ -778,7 +782,7 @@ function UpdatePackageVersions($pkgWorkItem, $plannedVersions, $shippedVersions)
 
   # If no version files to update do nothing
   if ($fieldUpdates.Count -eq 0) {
-    return
+    return $pkgWorkItem
   }
 
   $versionsForDebug = ($versionList | Foreach-Object { $_.Version }) -join ","
@@ -798,13 +802,14 @@ function UpdatePackageVersions($pkgWorkItem, $plannedVersions, $shippedVersions)
     $encodedToken = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes([string]::Format("{0}:{1}", "", $devops_pat)))
     $headers = @{ Authorization = "Basic $encodedToken" }
   }
-  else 
+  else
   {
     # Get a temp access token from the logged in az cli user for azure devops resource
     $jwt_accessToken = (az account get-access-token --resource "499b84ac-1321-427f-aa17-267ca6975798" --query "accessToken" --output tsv)
     $headers = @{ Authorization = "Bearer $jwt_accessToken" }
   }
   $response = Invoke-RestMethod -Method PATCH `
     -Uri "https://dev.azure.com/azure-sdk/_apis/wit/workitems/${id}?api-version=6.0" `
-    -Headers $headers -Body $body -ContentType "application/json-patch+json"
+    -Headers $headers -Body $body -ContentType "application/json-patch+json" | ConvertTo-Json -Depth 10 | ConvertFrom-Json -AsHashTable
+  return $response
 }

eng/common/scripts/Package-Properties.ps1

@@ -171,12 +171,12 @@ function Get-PkgPropsForEntireService ($serviceDirectoryPath)
 function Get-ArtifactListFromYml ($ciYmlPath)
 {
     $ProgressPreference = "SilentlyContinue"
-    if ((Get-PSRepository | ?{$_.Name -eq "PSGallery"}).Count -eq 0)
+    if ((Get-PSRepository).Where({$_.Name -eq "PSGallery"}).Count -eq 0)
     {
         Register-PSRepository -Default -ErrorAction:SilentlyContinue
     }
 
-    if ((Get-Module -ListAvailable -Name powershell-yaml | ?{$_.Version -eq "0.4.2"}).Count -eq 0)
+    if ((Get-Module -ListAvailable -Name powershell-yaml).Where({ $_.Version -eq "0.4.2"} ).Count -eq 0)
     {
         Install-Module -Name powershell-yaml -RequiredVersion 0.4.2 -Force -Scope CurrentUser
     }

eng/common/scripts/Prepare-Release.ps1

@@ -1,11 +1,50 @@
 #Requires -Version 6.0
 
+<#
+.SYNOPSIS
+This script will do the necessary book keeping work needed to release a package.
+
+.DESCRIPTION
+This script will do a number of things when ran:
+
+- It will read the current version from the project and will have you confirm if that is the version you want to ship
+- It will take the package metadata and version and update the DevOps release tracking items with that information.
+  - If there is existing release work item it will update it and if not it will create one.
+- It will validate that the changelog has a entry for the package version that you want to release as well as a timestamp.
+
+.PARAMETER PackageName
+The full package name of the package you want to prepare for release. (i.e Azure.Core, azure-core, @azure/core-https)
+
+.PARAMETER ServiceDirectory
+Optional: The service directory where the package lives (e.g. /sdk/<service directory>/<package>). If a service directory isn't provided the script
+will search for the package project by traversing all the packages under /sdk/, so the service directory is only a scoping mechanism.
+
+.PARAMETER ReleaseDate
+Optional: If not shipping on the normal first Tuesday of the month you can specify a specific release date in the form of "MM/dd/yyyy".
+
+.PARAMETER ReleaseTrackingOnly
+Optional: If this switch is passed then the script will only update the release work items and not update the versions in the local repo or validate the changelog.
+
+.EXAMPLE
+PS> ./eng/common/scripts/Prepare-Release.ps1 <PackageName>
+
+The most common usage is to call the script passing the package name. Once the script is finished then you will have modified project and change log files.
+You should make any additional changes to the change log to capture the changes and then submit the PR for the final changes before you do a release.
+
+.EXAMPLE
+PS> ./eng/common/scripts/Prepare-Release.ps1 <PackageName> -ReleaseTrackingOnly
+
+If you aren't ready to do the final versioning changes yet but you want to update release tracking information for shiproom pass in the -ReleaseTrackingOnly.
+option. This should not modify or validate anything in the repo but will update the DevOps release tracking items. Once you are ready for the verioning changes
+as well then come back and run the full script again without the -ReleaseTrackingOnly option and give it the same version information you did the first time.
+#>
 [CmdletBinding()]
 param(
   [Parameter(Mandatory = $true)]
   [string]$PackageName,
   [string]$ServiceDirectory,
-  [string]$ReleaseDate # Pass Date in the form MM/dd/yyyy"
+  [string]$ReleaseDate, # Pass Date in the form MM/dd/yyyy"
+  [switch]$ReleaseTrackingOnly = $false
 )
 Set-StrictMode -Version 3
 
@@ -27,6 +66,7 @@ function Get-ReleaseDay($baseDate)
 
 $ErrorPreference = 'Stop'
 
+$packageProperties = $null
 $packageProperties = Get-PkgProperties -PackageName $PackageName -ServiceDirectory $ServiceDirectory
 
 if (!$packageProperties)
@@ -87,6 +127,24 @@ if ($null -eq $newVersionParsed)
   exit 1
 }
 
+&$EngCommonScriptsDir/Update-DevOps-Release-WorkItem.ps1 `
+  -language $LanguageDisplayName `
+  -packageName $packageProperties.Name `
+  -version $newVersion `
+  -plannedDate $releaseDateString `
+  -packageRepoPath $packageProperties.serviceDirectory `
+  -packageType $packageProperties.SDKType `
+  -packageNewLibrary $packageProperties.IsNewSDK
+
+if ($releaseTrackingOnly)
+{
+  Write-Host
+  Write-Host "Script is running in release tracking only mode so only updating the release tracker and not updating versions locally."
+  Write-Host "You will need to run this script again once you are ready to update the versions to ensure the projects and changelogs contain the correct version."
+
+  exit 0
+}
+
 if (Test-Path "Function:SetPackageVersion")
 {
   SetPackageVersion -PackageName $packageProperties.Name -Version $newVersion -ServiceDirectory $packageProperties.ServiceDirectory -ReleaseDate $releaseDateString `
@@ -100,19 +158,10 @@ else
   exit 1
 }
 
-&$EngCommonScriptsDir/Update-DevOps-Release-WorkItem.ps1 `
-  -language $LanguageDisplayName `
-  -packageName $packageProperties.Name `
-  -version $newVersion `
-  -plannedDate $releaseDateString `
-  -packageRepoPath $packageProperties.ServiceDirectory `
-  -packageType $packageProperties.SDKType `
-  -packageNewLibrary $packageProperties.IsNewSDK
-
 git diff -s --exit-code $packageProperties.DirectoryPath
 if ($LASTEXITCODE -ne 0)
 {
   git status
   Write-Host "Some changes were made to the repo source" -ForegroundColor Green
-  Write-Host "Submit a pull request with the necessary changes to the repo" -ForegroundColor Green
+  Write-Host "Submit a pull request with the necessary changes to the repo, including any final changelog entry updates." -ForegroundColor Green
 }

eng/common/scripts/Update-DevOps-Release-WorkItem.ps1

@@ -15,17 +15,18 @@ param(
   [string]$packageNewLibrary = "true",
   [string]$devops_pat = $env:DEVOPS_PAT
 )
+#Requires -Version 6.0
 Set-StrictMode -Version 3
 
-if (!(Get-Command az)) {
+if (!(Get-Command az -ErrorAction SilentlyContinue)) {
   Write-Host 'You must have the Azure CLI installed: https://aka.ms/azure-cli'
   exit 1
 }
 
 az extension show -n azure-devops > $null
 if (!$?){
-  Write-Host 'You must have the azure-devops extension run `az extension add --name azure-devops`'
-  exit 1
+  Write-Host 'Installing azure-devops extension'
+  az extension add --name azure-devops
 }
 
 . (Join-Path $PSScriptRoot SemVer.ps1)
@@ -90,7 +91,7 @@ if (!$workItem) {
   if (!$packageInfo.ServiceName) {
     Write-Host "We need a package service name to be used in various places and it should be consistent across languages for similar packages."
     while (($readInput = Read-Host -Prompt "Input the service name") -eq "") { }
-    $packageInfo.ServiceName = $readInput 
+    $packageInfo.ServiceName = $readInput
   }
   Write-Host "  ServiceName: $($packageInfo.ServiceName)"
   Write-Host "  PackageType: $packageType"
@@ -104,5 +105,6 @@ if (!$workItem) {
 }
 Write-Host "Marking item [$($workItem.id)]$($workItem.fields['System.Title']) as '$state' for '$releaseType'"
 $updatedWI = UpdatePackageWorkItemReleaseState -id $workItem.id -state "In Release" -releaseType $releaseType -outputCommand $false
-UpdatePackageVersions $workItem -plannedVersions $plannedVersions
-Write-Host "https://dev.azure.com/azure-sdk/Release/_workitems/edit/$($updatedWI.id)/"
+$updatedWI = UpdatePackageVersions $workItem -plannedVersions $plannedVersions
+
+Write-Host "Release tracking item is at https://dev.azure.com/azure-sdk/Release/_workitems/edit/$($updatedWI.id)/"