automated release process

.github/workflows/publish_packages.ps1

@@ -0,0 +1,55 @@
+param (
+  [Parameter(Mandatory)]
+  $packagesDir
+)
+
+function Start-Section($sectionName) {
+  Write-Output ''
+  Write-Output "*** $sectionName ***"
+}
+
+function Confirm-Exit-Code($commandName, $cmdOutput = "") {
+  Write-Debug "$cmdOutput (exit code: $LASTEXITCODE)"
+  if ($LASTEXITCODE -ne 0) {
+    $fc = $host.UI.RawUI.ForegroundColor
+    $host.UI.RawUI.ForegroundColor = "Yellow"
+    Write-Output $cmdOutput
+    $host.UI.RawUI.ForegroundColor = "Red"
+    Write-Output 'error' "  FAILED: ${commandName} ($LASTEXITCODE)"
+    $host.UI.RawUI.ForegroundColor = $fc
+    if (-not ($LASTEXITCODE -gt 0)) {
+      Exit 100
+    }
+    Exit $LASTEXITCODE
+  }
+  Write-Output "$commandName done."
+}
+
+function Publish-Packages-To-NuGet($settings) {
+  Start-Section 'Publish Packages to NuGet.org'
+  $files = Join-Path $settings.OutputDir '*.nupkg' -Resolve
+  foreach ($file in $files) {
+    Write-Output "Uploading $file"
+    Write-Output "dotnet nuget push $file -k $env:NUGET_PUBLISH_KEY -s https://api.nuget.org/v3/index.json --no-symbols --skip-duplicate"
+    dotnet nuget push $file -k $env:NUGET_PUBLISH_KEY -s https://api.nuget.org/v3/index.json --no-symbols --skip-duplicate
+    Confirm-Exit-Code "upload $file"
+  }
+}
+
+function Publish-Symbol-Packages-To-NuGet($settings) {
+  Start-Section 'Publish Symbol Packages to NuGet.org'
+  $files = Join-Path $settings.OutputDir '*.snupkg' -Resolve
+  foreach ($file in $files) {
+    Write-Output "Uploading $file"
+    Write-Output "dotnet nuget push $file -k $env:NUGET_PUBLISH_KEY -s https://api.nuget.org/v3/index.json --skip-duplicate"
+    dotnet nuget push $file -k $env:NUGET_PUBLISH_KEY -s https://api.nuget.org/v3/index.json --skip-duplicate
+    Confirm-Exit-Code "upload $file"
+  }
+}
+
+$settings = [PSCustomObject]@{
+  OutputDir = $packagesDir
+}
+
+Publish-Packages-To-NuGet $settings
+Publish-Symbol-Packages-To-NuGet $settings

.vscode/settings.json

@@ -10,5 +10,6 @@
     "cSpell.words": [
         "Quickstart",
         "Reqnroll"
-    ]
+    ],
+    "markdown.extension.toc.updateOnSave": false
 }

RELEASING.md

@@ -0,0 +1,67 @@
+# Releasing
+
+This document describes how to make a release using GitHub Actions.  
+
+There are two parts to making a release:
+
+* [Prepare the release](#prepare-the-release)
+* [Make the release](#make-the-release)
+
+If you're making a major or minor release it is recommended to discuss it with the other contributors upfront (e.g. on Discord).
+
+## Prepare the release
+
+Anyone with permission to push to the `main` branch can prepare a release.
+
+1. Add new information to `CHANGELOG.md`. Ideally the `CHANGELOG.md` should be up-to-date, but sometimes there will be accidental omissions when merging PRs.
+    * Use `git log --format=format:"* %s (%an)" --reverse <last-version-tag>..HEAD` to list all commits since the last release.
+    * Add changelog details under the `# [vNext]` heading; the release process will update this heading when it makes the release
+1. Check & update contributors list (if applicable)
+    * List recent contributors:
+      ```
+      git log --format=format:"%an <%ae>" --reverse <last-version-tag>..HEAD  | grep -vEi "(renovate|dependabot|Snyk)" | sort| uniq -i
+      ```
+    * Update contributors if necessary at the `Contributors of this release` part of the `# [vNext]` heading
+1. The release process by default assumes the new releases to be patch releases, and whenever we merge a change that would require a minor or even major version number based on  [semver](https://semver.org/), we update the version at that time accordingly. When preparing the release you just need to double-check if the version is correct. You can find the current version number in the `Directory.Build.props` file.
+
+## Make the release
+
+Only people in group [release-managers](https://github.com/orgs/reqnroll/teams/release-managers) can make releases and only from the `main` branch.
+
+### Making a preview release
+
+Preview releases (aka pre-releases) are releases with a version number containing a version suffix, i.e. `1.2.3-pre1234`. 
+
+Every CI build produces a set of pre-release packages with version numbers as `1.2.3-ciYYYYMMDD-BBB`, where `YYYYMMDD` refers to the date and `BBB` is the build number. We never publish these CI build packages but they can be used for exploratory testing.
+
+We generally try to avoid publishing pre-releases, but if necessary, they shoud follow the version schema as `1.2.3-preYYYYMMDD-BBB`.
+
+To release such a preview release, the following steps has to be done:
+
+1. Open the CI workflow at GitHub: https://github.com/reqnroll/Reqnroll/actions/workflows/ci.yml
+1. Choose the "Run workflow" button to trigger the release with the following settings:
+   * `deploy_packages`: checked
+   * `is_production_release`: not checked
+   * `custom_version_suffix`: set it to `preYYYYMMDD`, where `YYYYMMDD` refers to the current date, e.g. `pre20240515`
+   * `custom_configuration`: leave it on default
+1. The CI workflow runs and ideally passes all core and testing jobs, but will stop for approval before running the `release` job.
+1. Make sure everything is OK. You can even donwload the packages to be published for a smoke test if necessary. 
+1. If everything is fine, approve the deployment job.
+1. The job will publish the packages (but do not change the version or the changelog as this is only a preview release)
+
+### Making a production release
+
+Production releases (or just releases) are intended to use for any users. Their version number does not contain a version suffix.
+
+To release such a preview release, the following steps has to be done:
+
+1. Open the CI workflow at GitHub: https://github.com/reqnroll/Reqnroll/actions/workflows/ci.yml
+1. Choose the "Run workflow" button to trigger the release with the following settings:
+   * `deploy_packages`: checked
+   * `is_production_release`: checked
+   * `custom_version_suffix`: leave it empty
+   * `custom_configuration`: leave it on default
+1. The CI workflow runs and ideally passes all core and testing jobs, but will stop for approval before running the `release` job.
+1. Make sure everything is OK. You can even donwload the packages to be published for a smoke test if necessary. 
+1. If everything is fine, approve the deployment job.
+1. The job will publish the packages, tag the current commit and create a new commit with the updated version number and changelog header.

Reqnroll.sln

@@ -12,6 +12,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 		CONTRIBUTING.md = CONTRIBUTING.md
 		LICENSE = LICENSE
 		README.md = README.md
+		RELEASING.md = RELEASING.md
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "UnitTests", "UnitTests", "{0359B7D7-7E29-48E9-8DF9-7D1FACFA5CFA}"

Reqnroll/Reqnroll.csproj

@@ -46,8 +46,6 @@
     <ItemGroup>
       <Compile Include="$(ProjectDir)Analytics/AppInsights/AppInsightsInstrumentationKey.cs" />
     </ItemGroup>
-
-    <ReplaceTextInFileTask Condition="'$(BuildingInsideVisualStudio)' != 'true'" InputFile="$(MSBuildThisFileDirectory)\..\CHANGELOG.md" OutputFile="$(MSBuildThisFileDirectory)\..\CHANGELOG.md" TextToReplace="[vNext]" TextToReplaceWith="v$(Version) - $([System.DateTime]::Now.ToString('yyyy-MM-dd'))" WriteOnlyWhenChanged="true" />
   </Target>
 
 </Project>