normalize builds

.github/workflows/build.yml

@@ -222,14 +222,34 @@ jobs:
   create-release:
     needs: [build-nrf, build-esp32-companions, build-esp32-repeaters, build-linux]
     runs-on: ubuntu-latest
+    # Needs write to create the release AND to delete/replace an existing one for
+    # the same version (see the "replace existing release" step below).
+    permissions:
+      contents: write
     outputs:
       release_tag: ${{ steps.tag.outputs.release_tag }}
 
     steps:
-    - name: generate release tag
+    - uses: actions/checkout@v6
+
+    # Tag the release with the firmware version string itself (the single source
+    # of truth in zephcore/CMakeLists.txt), NOT a build timestamp. The same value
+    # becomes the Mesh America catalog's version key, so the configurator can
+    # compare a running device's reported firmware against the catalog and know
+    # it's up to date. A timestamp tag could never match what the device reports.
+    #
+    # NOTE: the tag is only unique per version — pushing master again without
+    # bumping ZEPHCORE_FIRMWARE_VERSION updates the existing release in place
+    # rather than cutting a new one. Bump the version to cut a new release.
+    - name: derive release tag from firmware version
       id: tag
       run: |
-        version=v$(date +"%Y%m%d.%H%M%S")
+        version=$(sed -n 's/^set(ZEPHCORE_FIRMWARE_VERSION "\(.*\)")/\1/p' zephcore/CMakeLists.txt)
+        if [ -z "$version" ]; then
+          echo "::error::Could not read ZEPHCORE_FIRMWARE_VERSION from zephcore/CMakeLists.txt"
+          exit 1
+        fi
+        echo "Release tag / catalog version: $version"
         echo "release_tag=$version" >> $GITHUB_OUTPUT
 
     - uses: actions/cache/restore@v5
@@ -258,6 +278,44 @@ jobs:
         name: firmware-${{ steps.tag.outputs.release_tag }}
         path: firmware
 
+    # Publish releasenotes/RELEASE_NOTES_<version>.md as the release body. The
+    # filename matches the firmware version string exactly (= the release tag), so
+    # this is a direct lookup with no name munging. Write the notes for a version
+    # before bumping to it; a missing file only warns (empty body), never fails
+    # the release.
+    - name: resolve release notes
+      id: notes
+      run: |
+        notes="releasenotes/RELEASE_NOTES_${{ steps.tag.outputs.release_tag }}.md"
+        if [ -f "$notes" ]; then
+          echo "Using release notes: $notes"
+          echo "notes_path=$notes" >> $GITHUB_OUTPUT
+        else
+          echo "::warning::No release notes at $notes — publishing with an empty body"
+          : > "${RUNNER_TEMP}/empty_notes.md"
+          echo "notes_path=${RUNNER_TEMP}/empty_notes.md" >> $GITHUB_OUTPUT
+        fi
+
+    # Replace any existing release for this version instead of piling onto it.
+    # Since the tag is the firmware version, re-pushing master without a bump
+    # reuses the tag. action-gh-release only overwrites assets with the SAME
+    # name, but our firmware filenames embed the commit hash — so a rebuild would
+    # ADD ~100 new assets beside the old ones and leave the tag pinned to the old
+    # commit. Deleting first (with the tag) makes each build a clean replacement:
+    # current assets only, tag re-created on the building commit.
+    # `|| true` — the first release of a version has nothing to delete.
+    - name: replace existing release for this version
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        tag="${{ steps.tag.outputs.release_tag }}"
+        if gh release view "$tag" >/dev/null 2>&1; then
+          echo "Existing release $tag found — deleting it (and its tag) so this build replaces it"
+          gh release delete "$tag" --yes --cleanup-tag || true
+        else
+          echo "No existing release for $tag — creating a new one"
+        fi
+
     - name: create release
       uses: softprops/action-gh-release@v2
       env:
@@ -265,7 +323,8 @@ jobs:
       with:
         tag_name: ${{ steps.tag.outputs.release_tag }}
         name: Firmware ${{ steps.tag.outputs.release_tag }}
-        body: ""
+        body_path: ${{ steps.notes.outputs.notes_path }}
+        target_commitish: ${{ github.sha }}
         draft: false
         files: firmware/*