From 74ff2a04415691361b07b7dbd1d4762ad79bd82c Mon Sep 17 00:00:00 2001
From: Billy O'Neal <bion@microsoft.com>
Date: Wed, 11 May 2022 12:18:31 -0700
Subject: [PATCH] [docs] Add catalog release process. (#24647)

* [docs] Add catalog release process.

Also fixes https://github.com/microsoft/vcpkg/issues/23387
Also sorts added and changed ports by port name in the generated release notes
Also makes the formatting more consistent with GitHub's default generated release notes ("by foo, in #bar")

* Fix docs links.

* Add a space for additional PRs for new ports.
---
 .../internal/vcpkg_catalog_release_process.md | 14 ++++++++++++
 scripts/Get-Changelog.ps1                     | 22 ++++++++-----------
 2 files changed, 23 insertions(+), 13 deletions(-)
 create mode 100644 docs/maintainers/internal/vcpkg_catalog_release_process.md

diff --git a/docs/maintainers/internal/vcpkg_catalog_release_process.md b/docs/maintainers/internal/vcpkg_catalog_release_process.md
new file mode 100644
index 0000000000..0ea8922d58
--- /dev/null
+++ b/docs/maintainers/internal/vcpkg_catalog_release_process.md
@@ -0,0 +1,14 @@
+# vcpkg_tool_release_process
+
+This document describes the acceptance criteria / process we use when doing a vcpkg release.
+
+1. Generate a new GitHub Personal Access Token with repo permissions.
+2. Using the PAT, invoke $/scripts/Get-Changelog.ps1 `-StartDate (previous release date) -EndDate (Get-Date) -OutFile path/to/results.md`
+3. Create a new GitHub release in this repo.
+4. Submit a vcpkg.ci (full tree rebuild) run with the same SHA as that release.
+5. Use the "auto-generate release notes". Copy the "new contributors" and "full changelog" parts to the end of `path/to/results.md`.
+6. Change `## New Contributors` to `#### New Contributors`
+7. In `path/to/results.md`, update `LINK TO BUILD` with the most recent link to vcpkg.ci run.
+8. In `path/to/results.md`, fill out the tables for number of existing ports and successful ports.
+9. Replace the contents of the release notes with the contents of `path/to/results.md`
+10. After the full rebuild submission completes, update the link to the one for the exact SHA, the counts, and remove "(tentative)".
diff --git a/scripts/Get-Changelog.ps1 b/scripts/Get-Changelog.ps1
index 68f02957e3..5beebce6ec 100644
--- a/scripts/Get-Changelog.ps1
+++ b/scripts/Get-Changelog.ps1
@@ -405,7 +405,7 @@ $output = @"
 vcpkg ($($StartDate.ToString('yyyy.MM.dd')) - $((($EndDate).AddSeconds(-1)).ToString('yyyy.MM.dd')))
 ---
 #### Total port count:
-#### Total port count per triplet (tested):
+#### Total port count per triplet (tested) (tentative): LINK TO BUILD
 |triplet|ports available|
 |---|---|
 |x86-windows|NUM|
@@ -424,12 +424,12 @@ if ($UpdatedDocumentation) {
     $output += @"
 #### The following documentation has been updated:
 
-$(-join ($UpdatedDocumentation | ForEach-Object {
+$(-join ($UpdatedDocumentation | Sort-Object -Property 'Path' | ForEach-Object {
     $PathWithoutDocs =  ([string]$_.Path).Remove(0, 5) # 'docs/'
-    "- [{0}]({0}){1}`n" -f $PathWithoutDocs, $_.Path, ($(if ($_.New) { ' ***[NEW]***' } else { '' }))
+    "- [{0}](https://github.com/microsoft/vcpkg/blob/master/docs/{0}){1}`n" -f $PathWithoutDocs, ($(if ($_.New) { ' ***[NEW]***' } else { '' }))
 
     $_.Pulls | ForEach-Object {
-        "    - [(#{0})]({1}) {2} (by @{3})`n" -f $_.number, $_.html_url, $_.title, $_.user.login
+        "    - {0} (by @{1}, in #{2})`n" -f $_.title, $_.user.login, $_.number
     }
 }))
 
@@ -443,13 +443,13 @@ if ($NewPorts) {
 
 |port|version|
 |---|---|
-$(-join ($NewPorts | ForEach-Object {
+$(-join ($NewPorts | Sort-Object -Property 'Port' | ForEach-Object {
     "|[{0}]({1})" -f $_.Port, $_.Pulls[0].html_url
 
     if ($_.Pulls.Length -gt 1 ) {
         '<sup>'
         $_.Pulls[1..($_.Pulls.Length - 1)] | ForEach-Object {
-            "[#{0}]({1})" -f $_.number, $_.html_url
+            " #{0}" -f $_.number
         }
         '</sup>'
     }
@@ -466,13 +466,13 @@ if ($ChangedPorts) {
 <details>
 <summary><b>The following $($ChangedPorts.Length) ports have been updated:</b></summary>
 
-$(-join ($ChangedPorts | ForEach-Object {
+$(-join ($ChangedPorts | Sort-Object -Property 'Port' | ForEach-Object {
     "- {0} ``{1}#{2}``" -f $_.Port, $_.Version.Begin, $_.Version.BeginPort
     ' -> '
     "``{0}#{1}```n" -f $_.Version.End, $_.Version.EndPort
 
     $_.Pulls | ForEach-Object {
-        "    - [(#{0})]({1}) {2} (by @{3})`n" -f $_.number, $_.html_url, $_.title, $_.user.login
+        "    - {0} (by @{1}, in #{2})`n" -f $_.title, $_.user.login, $_.number
     }
 }))
 </details>
@@ -486,17 +486,13 @@ if ($UpdatedInfrastructure) {
 <summary>The following additional changes have been made to vcpkg's infrastructure:</summary>
 
 $(-join ($UpdatedInfrastructure | ForEach-Object {
-    "- [(#{0})]({1}) {2} (by @{3})`n" -f $_.number, $_.html_url, $_.title, $_.user.login
+    "- {0} (by @{1}, in #{2})`n" -f $_.title, $_.user.login, $_.number
 }))
 </details>
 
 "@
 }
 
-$output += @"
--- vcpkg team vcpkg@microsoft.com $(Get-Date -UFormat "%a, %d %B %T %Z00")
-"@
-
 Set-Content -Value $Output -Path $OutFile
 
 Write-Progress -Activity 'Writing changelog file' -Completed