ci: treat the native release assets as one set, not a bag of files

manifest.json pins a sha256 for every zip and the installers verify against
it, so uploading only the missing members of a partial set would pair zips
from one build with checksums from another — a rebuild is not guaranteed to be
byte-identical even at the same commit. Upload all of them or none, and stop
the job on a partial set so a person decides between keeping what is published
and cutting the next patch.

Also label the example fence in CONTRIBUTING.md.

Author: elkaix

.github/workflows/release.yml

@@ -650,10 +650,15 @@ jobs:
       # source change would put different bytes behind a version number users
       # already have. A version has to identify one exact build forever.
       #
-      # Uploading only what is missing keeps both properties: a run that failed
-      # part way through still completes on a re-run, and a rebuild of an
-      # already-published version is left on the floor instead of shipped under
-      # its old number. To correct a bad build, cut the next patch.
+      # These assets are one set, not a bag of files: manifest.json pins a
+      # sha256 for every zip, and install.sh / install.ps1 verify against it.
+      # So the rule is all or nothing. A release that already carries the whole
+      # set is finished and is left alone; an empty one gets everything. A
+      # partial set stops the job, because filling in the gaps would pair zips
+      # from one build with checksums from another, and a rebuild is not
+      # guaranteed to be byte-identical even at the same commit. Sorting that
+      # out is a decision for a person: either what is published is the
+      # release, or it needs a new patch version.
       - name: Upload assets to GitHub Release
         shell: bash
         env:
@@ -662,21 +667,24 @@ jobs:
         run: |
           set -euo pipefail
           existing="$(gh release view "$RELEASE_TAG" --json assets --jq '.assets[].name')"
-          missing=()
-          skipped=()
+          present=()
+          absent=()
           for path in dist-native-release/*; do
             name="$(basename "$path")"
             if printf '%s\n' "$existing" | grep -qxF "$name"; then
-              skipped+=("$name")
+              present+=("$name")
             else
-              missing+=("$path")
+              absent+=("$path")
             fi
           done
-          if [ "${#skipped[@]}" -gt 0 ]; then
-            echo "::notice::Already on ${RELEASE_TAG} and left untouched: ${skipped[*]}"
-          fi
-          if [ "${#missing[@]}" -eq 0 ]; then
-            echo "::notice::Every asset is already on ${RELEASE_TAG}; nothing to upload."
+          if [ "${#absent[@]}" -eq 0 ]; then
+            echo "::notice::All ${#present[@]} assets are already on ${RELEASE_TAG}; nothing to upload."
             exit 0
           fi
-          gh release upload "$RELEASE_TAG" "${missing[@]}"
+          if [ "${#present[@]}" -gt 0 ]; then
+            echo "::error::${RELEASE_TAG} already carries ${#present[@]} of these assets: ${present[*]}"
+            echo "::error::Adding the rest would mix two builds behind one version - manifest.json pins a sha256 per zip."
+            echo "::error::Resolve by hand: keep what is published, or cut the next patch and release that instead."
+            exit 1
+          fi
+          gh release upload "$RELEASE_TAG" "${absent[@]}"

CONTRIBUTING.md

@@ -92,7 +92,7 @@ Pythinker Code follows semantic versioning. The commit type you would have writt
 
 Each number counts on its own and none of them roll over at nine. Ten fixes on top of `1.2.0` land on `1.2.10`, not `1.3.0`; the minor moves only when a feature ships, and the major only when something breaks:
 
-```
+```text
 1.2.9  + fix      → 1.2.10
 1.9.9  + fix      → 1.9.10
 1.9.9  + feature  → 1.10.0
@@ -116,7 +116,7 @@ Never do any of these:
 
 To correct a bad build, cut the next patch instead: fix the problem, bump, build from that exact commit, sign and notarize, and publish fresh artifacts under the new number. The updater then advertises the new version, and anyone who already installed the old one keeps a build that still matches what it claims to be.
 
-CI enforces this rather than trusting the rule. The desktop release uploads into a draft and refuses to touch a release that is already published; the native CLI job uploads only assets that are missing, so a run that failed part way through still completes while a rebuild of a shipped version is left on the floor.
+CI enforces this rather than trusting the rule. The desktop release uploads into a draft and refuses to touch a release that is already published. The native CLI job treats its assets as one set — `manifest.json` pins a sha256 for every zip — so it uploads all of them or none: a release that already has the full set is left alone, and a partial set stops the job rather than pairing zips from one build with checksums from another.
 
 ### Release cadence