automated release process (#297)

* document release process

* Update CI with revised input params and version calculation

* fix comments in CI

* update artifact names

* add release job

* disable condition on release job for testing

* list release_packages folder for test

* disable condition on release job steps for testing

* move CHANGELOG update from MsBuild to CI

* fix CHANGELOG.md version header

* add publish packages script (does not use real key!)

* small fixes

* use right env var for publish

* disable actual publishing for testing

* Create GitHub Release

* update RELEASING.md

* Revert disabling details for testing

Revert "disable condition on release job for testing"

This reverts commit 2db30a5.

Revert "disable condition on release job steps for testing"

This reverts commit 9299289.

Revert "disable actual publishing for testing"

This reverts commit 2990d53.

# Conflicts:
#	.github/workflows/ci.yml

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