Say what each release gives people, in one place

.azure/pipelines/build-whiteboard.yaml

@@ -68,6 +68,11 @@ trigger:
     # that is byte-identical to the one before it.
     - installer/winget
     - scripts/build-release-manifests.ps1
+    # The notes for a release that already exists, and the script that reads them. A
+    # wording fix should not cut a pre-release; the notes for a version that has not
+    # shipped arrive with the VersionPrefix bump, which does trigger one.
+    - CHANGELOG.md
+    - scripts/release-notes.ps1
     # The same reasoning, one file rather than the folder: the rest of installer/msix is
     # the package manifest and its assets, which do go into a build. The listing text is
     # a record of what was typed into Partner Center by hand and is read by nothing.
@@ -361,6 +366,25 @@ stages:
             parameters:
               channel: stable
 
+          # The release body used to be the one line "SQLBI Whiteboard <version>.", which
+          # told a reader nothing, and addChangeLog would have replaced it with a list of
+          # commit subjects, which tells them too much of the wrong kind. Both come from
+          # CHANGELOG.md instead, so the release page and the What's new page on the site
+          # carry the same words and those words are written once.
+          #
+          # This fails the stage when the version has no entry. That is the point: the
+          # release has not been created yet when it runs, so an unwritten changelog stops
+          # the release rather than being noticed after it is public.
+          - task: PowerShell@2
+            displayName: 'Take the release notes from CHANGELOG.md'
+            inputs:
+              filePath: 'scripts/release-notes.ps1'
+              arguments: >-
+                -Mode Markdown
+                -Version $(AppSemVer)
+                -OutFile "$(Build.ArtifactStagingDirectory)/release-notes.md"
+              pwsh: true
+
           - task: GitHubRelease@1
             displayName: 'Create the GitHub release'
             inputs:
@@ -373,9 +397,8 @@ stages:
               # same version twice: bump VersionPrefix instead.
               tag: 'v$(AppSemVer)'
               title: 'SQLBI Whiteboard $(AppSemVer)'
-              releaseNotesSource: inline
-              releaseNotes: |
-                SQLBI Whiteboard $(AppSemVer).
+              releaseNotesSource: filePath
+              releaseNotesFilePath: '$(Build.ArtifactStagingDirectory)/release-notes.md'
               assets: '$(Build.ArtifactStagingDirectory)/release/*'
               isPreRelease: false
               addChangeLog: false

.github/workflows/publish-site.yml

@@ -25,8 +25,10 @@ on:
     branches: [main]
     paths:
       - 'site/**'
+      - 'CHANGELOG.md'
       - 'scripts/build-release-manifests.ps1'
       - 'scripts/verify-published-site.ps1'
+      - 'scripts/release-notes.ps1'
       - '.github/workflows/publish-site.yml'
   # A release changes what the manifests say without changing anything in site/, so it has
   # to redeploy the page as well. This is what keeps the download links current.
@@ -68,6 +70,25 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           EXPECT_TAG: ${{ github.event.release.tag_name }}
 
+      # A released version with no entry in CHANGELOG.md would publish a What's new page
+      # that does not mention the version people are being offered. Checked here as well as
+      # on the pull request that bumps VersionPrefix, because a release does not have to
+      # have come from one. Pre-releases are exempt: Dev builds come from every merge and
+      # are deliberately not in the changelog.
+      - name: Check this release has notes
+        if: github.event_name == 'release' && github.event.release.prerelease == false
+        shell: pwsh
+        run: ./scripts/release-notes.ps1 -Mode Verify -Version "$env:RELEASE_TAG"
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+
+      # Written into the page rather than fetched from the API by the page itself: the
+      # notes are then in the HTML that ships, so they are readable without scripting and
+      # findable by a search engine.
+      - name: Write the release notes into the page
+        shell: pwsh
+        run: ./scripts/release-notes.ps1 -Mode Html
+
       - uses: actions/configure-pages@v5
 
       - uses: actions/upload-pages-artifact@v3

.github/workflows/pull-request.yml

@@ -56,6 +56,42 @@ jobs:
             echo "-> nothing to build: only the site, docs, vscode extension or markdown changed"
           fi
 
+  # Release notes are written while the change is fresh, in the pull request that bumps the
+  # version, rather than remembered under pressure once the release is already public. The
+  # release itself is checked again in publish-site.yml.
+  notes:
+    name: Release notes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Check the version bump brings its notes
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Set-StrictMode -Version Latest
+
+          $base = "origin/$env:BASE_REF"
+          function Get-VersionPrefix([string]$text) {
+              if ($text -match '<VersionPrefix>(.*?)</VersionPrefix>') { return $Matches[1].Trim() }
+              return ''
+          }
+
+          $before = Get-VersionPrefix (git show "${base}:Directory.Build.props" | Out-String)
+          $after = Get-VersionPrefix (Get-Content Directory.Build.props -Raw)
+
+          if ($before -eq $after) {
+              Write-Host "VersionPrefix is unchanged at $after, so no new notes are due."
+              return
+          }
+
+          Write-Host "VersionPrefix goes $before -> $after."
+          ./scripts/release-notes.ps1 -Mode Verify -Version $after
+        env:
+          BASE_REF: ${{ github.base_ref }}
+
   build:
     name: Build and test
     needs: changes

CHANGELOG.md

@@ -0,0 +1,111 @@
+# What's new
+
+What a released version gives you that the one before it did not, written for the person
+deciding whether to upgrade rather than for the person who wrote the code.
+
+This file is the source for both the [What's new page](https://whiteboard.sqlbi.com/changelog.html)
+and the notes on each GitHub release, so it is written once and read in both places. Only
+released versions appear. Pre-release **Dev** builds are published continuously from `main`
+and are not listed here; their commit history is on GitHub. Nor are the releases before
+1.0.0, which built the application up to its first stable version and are on
+[GitHub Releases](https://github.com/sql-bi/SQLBI-Whiteboard/releases) with their own notes.
+
+**Adding an entry.** One `## <version> - <date>` heading, then one `###` heading per thing a
+person would notice, each with a sentence or two saying what changed and what it is for. A
+release with nothing worth noticing still needs an entry — say that it is a fix and what
+broke. The heading is parsed by `scripts/release-notes.ps1`, so keep its shape; the prose
+under it is ordinary Markdown, and the renderer handles paragraphs, lists, links, `code`
+and **bold**.
+
+## 1.2.2 - 2 September 2026
+
+### The Eraser, for a pen that has none
+Not every pen has an eraser on its back end, and until now those pens could not reach the
+Eraser tool at all — it appears on the toolbar only when finger or mouse drawing puts it
+there. **Preferences → Toolbar → Always show the Eraser** keeps it there for the pen too.
+It is off by default, so nothing changes for a pen that already erases. In the compact
+toolbar layouts the Eraser joins the row of tools rather than taking a row of its own.
+
+### Preferences you can read
+Every setting is now one line: a title and a single sentence saying what it is for. The
+defaults, the reasoning and the consequences moved behind a chevron, so a category can be
+skimmed instead of read. Searching marks what it matched, and marks the chevron when the
+match is in the text behind it, and the search box has a button to clear it.
+
+## 1.2.1 - 31 August 2026
+
+### Mouse drawing offers itself
+With Mouse drawing off, picking a tool from the toolbar with the mouse now offers to turn
+it on. Reaching for the palette with a mouse is the one moment the application can be sure
+the question is worth asking — a pen user reaches for it with the pen. The offer appears
+once a session, and once declined for good it does not come back.
+
+## 1.2.0 - 30 August 2026
+
+### The mouse can draw
+The left mouse button now does what the selected tool does: ink, erase, select, pan, or the
+laser. It defaults to on when Windows reports neither a pen tablet nor a touchscreen, so a
+machine with nothing else to draw with works out of the box.
+
+Everything the left button used to do moves to **Ctrl**: Ctrl and the left button select,
+move and resize a container, and Ctrl with a double-click centers and fits one. A mouse
+reports no pressure, so ink is drawn at an even width, and Calligraphy is the one tool that
+still varies because its width comes from speed. The pen path is untouched, so this can be
+left on beside a pen.
+
+## 1.1.5 - 29 August 2026
+
+### A word at startup when there is nothing to draw with
+When Windows reports neither a pen tablet nor a touchscreen, the application now says so at
+startup and explains what it is drawing with instead. Dismissable from the notice or from
+Preferences, because the list Windows reports can miss a pen that has never been in range.
+
+### Setting choices that do not clip their labels
+The drawn choices in Preferences — toolbar position, pen button, laser weight — reflow onto
+another row instead of squeezing until their labels are cut off mid-word.
+
+## 1.1.2 - 27 August 2026
+
+### Ink over an image, not under it
+A stroke drawn across an imported image, text container or LiveView now appears over it
+while you are drawing, as it already did once the stroke was finished.
+
+## 1.1.1 - 26 August 2026
+
+### Steadier pen ink, and straight lines
+Pen strokes are now collected from the pen's own points rather than from the ink layer,
+which keeps pressure and timing intact along the whole stroke. Holding **Shift** rules a
+stroke straight, and **Straight line** is available as the pen barrel button action in
+Preferences.
+
+## 1.1.0 - 25 August 2026
+
+### SVG images stay vector
+SVG files can be imported like any other image, and stay vector — so they are still sharp
+after zooming in or scaling the container up.
+
+## 1.0.3 - 25 August 2026
+
+### LiveView stability
+Fixes a crash caused by releasing a LiveView frame surface more than once.
+
+## 1.0.2 - 25 August 2026
+
+### LiveView stability
+Fixes a crash in Windows Graphics Capture by keeping it on the UI thread.
+
+## 1.0.1 - 25 August 2026
+
+### LiveView stability in the Store build
+Fixes a crash when a LiveView was resized in the Microsoft Store build.
+
+## 1.0.0 - 23 August 2026
+
+### The pen says what a tap would do
+While the pen hovers, the board shows what touching down would do: the laser with its halo
+and speed trail, a dashed square around what the eraser would clear, and a high-contrast
+dot for everything else. All of them disappear on contact.
+
+### 1.0
+Everything 1.0 was waiting on had shipped: Preferences, `.wimport` recipes, Explorer and
+VS Code previews, the documentation site, and finger drawing.

CONTRIBUTING.md

@@ -64,6 +64,13 @@ need not be publication quality.
 an unsigned assembly would ship beside a signed executable unnoticed. This has happened once
 already.
 
+**Bumping the version means writing the release notes.** A pull request that changes
+`VersionPrefix` in `Directory.Build.props` must add a matching `## <version> - <date>`
+section to `CHANGELOG.md`, or the **Release notes** check fails. Write what a person gets
+by upgrading, not what the diff did — that file becomes the GitHub release body and the
+[What's new](https://whiteboard.sqlbi.com/changelog.html) page, so it is the only version
+history most people will ever read. Pre-release Dev builds need no entry.
+
 **Brand assets are generated.** Only `src/SQLBI.Whiteboard/Assets/SQLBI.Whiteboard.svg` is
 authored. Icons, installer artwork, and web assets come from `scripts/build-assets.ps1`, and
 hand edits are lost on the next run. Colors must change in both the SVG and

docs/release-management.md

@@ -12,7 +12,8 @@ itself. Do not run it to “release” anything.
 | You want to | Do this |
 | --- | --- |
 | Land a change | Open a pull request against `main`. The **Pull request** Action builds and tests; merge when it is green. |
-| Ship a Whiteboard pre-release | Merge to `main` (anything except `docs/`, `site/`, `vscode/`, and top-level markdown). Azure Pipelines **SQLBI Whiteboard** signs and publishes the GitHub prerelease. To rebuild an existing commit: Azure DevOps → that pipeline → **Run pipeline**. Do not use **Re-run**. |
+| Ship a Whiteboard pre-release | Merge to `main` (anything except `docs/`, `site/`, `vscode/`, `CHANGELOG.md`, and top-level markdown). Azure Pipelines **SQLBI Whiteboard** signs and publishes the GitHub prerelease. To rebuild an existing commit: Azure DevOps → that pipeline → **Run pipeline**. Do not use **Re-run**. |
+| Say what a release gives people | Add a `## <version> - <date>` section to `CHANGELOG.md`, in the same pull request that bumps `VersionPrefix`. The **Release notes** check fails without it. That one file becomes both the GitHub release body and the [What's new](https://whiteboard.sqlbi.com/changelog.html) page. |
 | Promote that build to a full release | Approve the **Release** stage of the same Azure run. Nothing is rebuilt. |
 | Ship a VS Code extension update | Bump `version` in `vscode/sqlbi-whiteboard/package.json` in a pull request and merge. The **Publish VS Code extension** Action publishes `sqlbi.sqlbi-whiteboard` if that version is not already on the Marketplace. To retry: Actions → **Publish VS Code extension** → **Run workflow**. |
 | Update whiteboard.sqlbi.com | Merge a change under `site/`. The **Publish site** Action deploys. To retry: Actions → **Publish site** → **Run workflow**. |
@@ -132,6 +133,37 @@ variables → Actions**. Forks never receive it.
 when that tree changes on `main`, when a release is published, and on **Run workflow**.
 `site/CNAME` carries the custom domain.
 
+### Release notes
+
+`CHANGELOG.md` is the only place release notes are written, and `scripts/release-notes.ps1`
+is the only thing that reads it. One `## <version> - <date>` section per released version,
+one `###` heading per thing a person would notice.
+
+It has three readers, and none of them can be satisfied by the other two:
+
+- The **Release notes** check on every pull request fails when `Directory.Build.props`
+  changes `VersionPrefix` and no section exists for the new version. This is the gate that
+  matters: the notes get written while the change is fresh, by the person who made it.
+- **Azure Pipelines** writes that section into the GitHub release body. It used to be the
+  single line `SQLBI Whiteboard <version>.`, which told a reader nothing; `addChangeLog`
+  would have told them a list of commit subjects, which is not the same as what they get.
+  The step runs before the release is created, so an unwritten changelog stops the release
+  instead of being noticed afterwards.
+- **Publish site** renders every section into `site/changelog.html`, between its
+  `<!-- releases:start -->` and `<!-- releases:end -->` markers, and refuses to deploy a
+  published release that has no section. The page carries the notes as HTML rather than
+  fetching them from the GitHub API as it used to, so they are readable without scripting
+  and findable by a search engine.
+
+Pre-release **Dev** builds are deliberately absent: they come from every merge to `main`
+and would bury the releases people actually choose between. The release-time check exempts
+them.
+
+The renderer handles the subset the changelog is allowed to use — `###` headings,
+paragraphs, lists, links, `code`, and **bold**. Anything outside that subset appears as
+plain text rather than as broken markup, which for a file we write ourselves is a style
+rule rather than a limitation.
+
 Two settings outside the repository have to be right, and each fails in its own quiet way:
 
 - **Settings → Pages → Source: GitHub Actions.** With the default "Deploy from a branch"

installer/winget/SQLBI.Whiteboard.installer.yaml

@@ -16,23 +16,23 @@
 # release except the one it was copied from. `wingetcreate update` reads it out of the
 # downloaded MSI at submission time, which is the only way it can be right.
 PackageIdentifier: SQLBI.Whiteboard
-PackageVersion: 0.9.2
+PackageVersion: 1.2.2
 MinimumOSVersion: 10.0.19041.0
 InstallerType: wix
 InstallModes:
 - interactive
 - silent
 - silentWithProgress
 UpgradeBehavior: install
-ReleaseDate: '2026-08-19'
+ReleaseDate: '2026-09-02'
 Installers:
 - Architecture: x64
   Scope: machine
-  InstallerUrl: https://github.com/sql-bi/SQLBI-Whiteboard/releases/download/v0.9.2/SQLBI.Whiteboard.0.9.2.x64.msi
-  InstallerSha256: CF7AC4C5F4AED82382811CE00B606D13E99BA08AB9804FD05E68D23E0689CBE9
+  InstallerUrl: https://github.com/sql-bi/SQLBI-Whiteboard/releases/download/v1.2.2/SQLBI.Whiteboard.1.2.2.x64.msi
+  InstallerSha256: 10574E89368DA3E56A4C739C44096A2570F8C1FB9355344BAED197F1E1AA9A21
 - Architecture: x64
   Scope: user
-  InstallerUrl: https://github.com/sql-bi/SQLBI-Whiteboard/releases/download/v0.9.2/SQLBI.Whiteboard.0.9.2.x64-userinstaller.msi
-  InstallerSha256: 9885733D3E0AAEBC39ABC0F142C7461EEA7DE0B5F20CD184A50EACAE19D5BE9B
+  InstallerUrl: https://github.com/sql-bi/SQLBI-Whiteboard/releases/download/v1.2.2/SQLBI.Whiteboard.1.2.2.x64-userinstaller.msi
+  InstallerSha256: 2D5E25F28AA9820DA6D20DDFB640456FB4F6D5034E1F932A6DD0637EB816B3ED
 ManifestType: installer
 ManifestVersion: 1.6.0

installer/winget/SQLBI.Whiteboard.locale.en-US.yaml

@@ -4,7 +4,7 @@
 # describing the same application differently is a difference a reader has to resolve,
 # and there is nothing here worth resolving.
 PackageIdentifier: SQLBI.Whiteboard
-PackageVersion: 0.9.2
+PackageVersion: 1.2.2
 PackageLocale: en-US
 Publisher: SQLBI Corp
 PublisherUrl: https://www.sqlbi.com

installer/winget/SQLBI.Whiteboard.yaml

@@ -8,7 +8,7 @@
 # They are kept here anyway: a submission is a pull request against someone else's
 # repository, and the version of it that was sent needs to be reviewable in this one.
 PackageIdentifier: SQLBI.Whiteboard
-PackageVersion: 0.9.2
+PackageVersion: 1.2.2
 DefaultLocale: en-US
 ManifestType: version
 ManifestVersion: 1.6.0