[docs] Add catalog release process. (#24647)

* [docs] Add catalog release process.

Also fixes #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.

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)".

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