Extended release action

Author: manuelbl

.config/dotnet-tools.json

@@ -3,18 +3,18 @@
   "isRoot": true,
   "tools": {
     "dotnet-validate": {
-      "version": "0.0.1-preview.304",
+      "version": "0.0.1-preview.537",
       "commands": [
         "dotnet-validate"
       ],
-      "rollForward": false
+      "rollForward": true
     },
     "docfx": {
       "version": "2.78.5",
       "commands": [
         "docfx"
       ],
-      "rollForward": false
+      "rollForward": true
     }
   }
 }

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
     name: Publish to NuGet
     environment: nuget
     permissions:
-      contents: read
+      contents: write
       id-token: write
     steps:
       - name: Checkout git repository
@@ -47,10 +47,20 @@ jobs:
       - name: Run tests
         run: dotnet test --verbosity normal
 
+      - name: Restore .NET tools
+        run: dotnet tool restore
+
       - name: Create and validate NuGet package
+        run: dotnet pack QrCodeGenerator/QrCodeGenerator.csproj --verbosity normal
+
+      - name: Create API documentation
+        run: dotnet docfx docfx/docfx.json --warningsAsErrors
+        working-directory: QrCodeGenerator
+
+      - name: Zip API documentation
+        shell: pwsh
         run: |
-          dotnet tool restore
-          dotnet pack QrCodeGenerator/QrCodeGenerator.csproj --verbosity normal
+          Compress-Archive -Path QrCodeGenerator/bin/_site/* -DestinationPath API.Documentation.zip -Force
 
       - name: NuGet login (OIDC to temporary API key)
         uses: NuGet/login@v1
@@ -65,3 +75,35 @@ jobs:
           --source https://api.nuget.org/v3/index.json
           --api-key ${{ steps.login.outputs.NUGET_API_KEY }}
           --skip-duplicate
+
+      - name: Create and push release tag
+        shell: pwsh
+        run: |
+          $tag = "v${{ steps.version.outputs.version }}"
+          if (git ls-remote --tags origin "refs/tags/$tag") {
+            Write-Host "Tag $tag already exists - skipping"
+            exit 0
+          }
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a $tag -m "Release $tag"
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          git push origin "refs/tags/$tag"
+
+      - name: Create draft GitHub release
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          $version = "${{ steps.version.outputs.version }}"
+          $tag = "v$version"
+          $assets = @(
+            "QrCodeGenerator/bin/Release/Net.Codecrete.QrCodeGenerator.$version.nupkg",
+            "API.Documentation.zip"
+          )
+          if (gh release view $tag 2>$null) {
+            gh release upload $tag $assets --clobber
+          } else {
+            gh release create $tag $assets --draft --title "$tag" --generate-notes
+          }
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }

RELEASING.md

@@ -2,27 +2,47 @@
 
 The library's version lives in three properties in
 [QrCodeGenerator/QrCodeGenerator.csproj](QrCodeGenerator/QrCodeGenerator.csproj):
-`Version`, `PackageVersion`, `FileVersion`. Between releases it
-carries a `-dev` prerelease suffix (e.g. `3.1.0-dev`) so it's always ordered above the
+`Version`, `PackageVersion`, `FileVersion`. Between releases `Version` and `PackageVersion`
+carry a `-dev` prerelease suffix (e.g. `3.1.0-dev`) so they're always ordered above the
 last release but never resolved by a floating `3.*` `PackageReference` (NuGet excludes
-prereleases from floating ranges by default). `README.md`, `QrCodeGenerator/docs/README.md`,
-and the demo projects' `PackageReference` versions stay pinned to the last published
-release at all times — they're only updated as part of a release, never in between.
+prereleases from floating ranges by default). `FileVersion` stays a plain four-part number
+(e.g. `3.1.0.0`) — it cannot hold a prerelease suffix. `AssemblyVersion` is only bumped on
+breaking changes and is not touched by a release.
+
+`README.md`, `QrCodeGenerator/docs/README.md` and `QrCodeGenerator/docfx/api/index.md` stay
+pinned to the last published release at all times — they're only updated as part of a
+release, never in between. This way everyone cloning the repository reads instructions for a
+package actually available on nuget.org. The demo projects need no such updating: they use a
+floating `Version="3.*"` `PackageReference`, which the `-dev` suffix keeps resolving to the
+last published release.
 
 ## Steps
 
-1. Update `QrCodeGenerator/QrCodeGenerator.csproj`: set `Version`, `PackageVersion`,
-   `FileVersion` (but not `AssemblyVersion`) to the release version `X.Y.Z` (drop the `-dev`
-   suffix), and update `PackageReleaseNotes`.
+1. Update `QrCodeGenerator/QrCodeGenerator.csproj`: set `Version` and `PackageVersion` to the
+   release version `X.Y.Z` (drop the `-dev` suffix), set `FileVersion` to `X.Y.Z.0` (but leave
+   `AssemblyVersion` alone), and update `PackageReleaseNotes`.
 2. Update `README.md`: install command and any prose version references → `X.Y.Z`.
 3. Update `QrCodeGenerator/docs/README.md` the same way, including its
    `.../blob/vX.Y.Z/...` tag-pinned links.
-5. Commit as `Release vX.Y.Z`, tag the commit `vX.Y.Z`, push commit and tag.
-6. `dotnet pack -c Release` and publish the resulting nupkg to nuget.org (manual today).
-7. Bump `QrCodeGenerator/QrCodeGenerator.csproj` to the next planned version with a
+4. Update `QrCodeGenerator/docfx/api/index.md`, which carries the same tag-pinned
+   `.../blob/vX.Y.Z/...` links.
+5. Commit as `Release vX.Y.Z` and push.
+6. Run the [*Publish Release to NuGet*](https://github.com/manuelbl/QrCodeGenerator/actions/workflows/release.yml)
+   workflow. It reads the version from `QrCodeGenerator/QrCodeGenerator.csproj`, runs the
+   tests, packs and publishes the package, generates the API documentation with docfx, and —
+   after a successful publish — creates and pushes the `vX.Y.Z` tag and creates a *draft*
+   GitHub release with the nupkg and `API.Documentation.zip` attached. The job only runs if
+   the deployment review is approved.
+7. Review the draft release on GitHub — edit the auto-generated notes, mark it as a
+   pre-release if applicable — and publish it.
+8. Bump `QrCodeGenerator/QrCodeGenerator.csproj` to the next planned version with a
    `-dev` suffix (e.g. `3.2.0-dev`), commit as `Bump version to 3.2.0-dev for development`.
-   Leave `README.md`, `QrCodeGenerator/docs/README.md`, and the demo projects untouched —
-   they keep pointing at `X.Y.Z` until the next release.
+   Leave `README.md`, `QrCodeGenerator/docs/README.md` and `QrCodeGenerator/docfx/api/index.md`
+   untouched — they keep pointing at `X.Y.Z` until the next release.
+
+The tag and draft-release steps are idempotent: re-running the workflow for a version that
+was already tagged skips the tag, and an existing release has its assets re-uploaded rather
+than being recreated.
 
 ## Why examples still build against HEAD
 
@@ -31,4 +51,4 @@ before building each demo, overrides that demo's resolved package version for th
 run only (`dotnet add package ... --source Local`, which rewrites the checked-out
 `.csproj` in the runner's workspace — nothing is committed). This means CI always
 validates the examples against the in-progress library code, even though the
-`PackageReference` version committed to the repo stays pinned to the last release.
+`PackageReference` version committed to the repo resolves to the last release.