* mirror current changelog/prune scripts from the shared template (notes-only mode, bot-commit filtering, prune retry + newest-kept guard)

* nightly: same-day re-runs replace release AND tag at the validated SHA
* release: the vyyyyMMdd tag is placed ON the changelog commit so bookkeeping never pollutes the next notes
* workflows trigger on main only after the rename

Author: Hawkynt

.github/workflows/ci.yml

@@ -4,9 +4,9 @@ name: CI
 # release.yml and nightly.yml reuse this via `workflow_call` / `workflow_run`.
 on:
   push:
-    branches: [master]
+    branches: [main]
   pull_request:
-    branches: [master]
+    branches: [main]
   workflow_call: {}
 
 # Force JavaScript-based actions to run on Node 24 instead of the deprecated Node 20 ahead of

.github/workflows/nightly.yml

@@ -5,7 +5,7 @@ name: Nightly
 on:
   workflow_run:
     workflows: [CI]
-    branches: [master]
+    branches: [main]
     types: [completed]
   workflow_dispatch: {}
 
@@ -48,13 +48,22 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
+      # --notes-only: CHANGELOG.md is committed by release.yml exclusively.
       - name: Generate release notes (functional changes, bucketed by + - * # !)
-        run: node ".github/workflows/scripts/update-changelog.mjs" --nightly --notes RELEASE_NOTES.md
+        run: node ".github/workflows/scripts/update-changelog.mjs" --nightly --notes-only --notes RELEASE_NOTES.md
+
+      # Same-day re-run: drop the existing nightly release AND its tag first,
+      # so the tag always points at the SHA that was actually built.
+      - name: Replace same-day nightly (release + tag), if any
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release delete "${{ env.NIGHTLY_TAG }}" --cleanup-tag --yes || true
       - name: Publish nightly prerelease
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ env.NIGHTLY_TAG }}
           name: ${{ env.NIGHTLY_TAG }}
+          target_commitish: ${{ github.event.workflow_run.head_sha || github.sha }}
           prerelease: true
           files: artifacts/*.nupkg
           body_path: RELEASE_NOTES.md           # commit-message changelog, not GitHub's PR notes

.github/workflows/release.yml

@@ -62,10 +62,12 @@ jobs:
             git commit -m "* update changelog for $REL [skip ci]"
             git push
           fi
-      - name: Create GitHub Release (dated marker; tags vyyyyMMdd)
+          echo "REL_SHA=$(git rev-parse HEAD)" >> "$GITHUB_ENV"
+      - name: Create GitHub Release (dated marker; tags vyyyyMMdd at the changelog commit)
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ env.REL }}
           name: ${{ env.REL }}
+          target_commitish: ${{ env.REL_SHA }}
           files: dist/*.nupkg
           body_path: RELEASE_NOTES.md            # commit-message changelog, not GitHub's PR notes

.github/workflows/scripts/prune-nightlies.mjs

@@ -10,6 +10,7 @@
 // Dry-run locally with `node .github/workflows/scripts/prune-nightlies.mjs --dry-run`.
 
 import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
 
 export const DAILY_KEEP   = 7;
 export const WEEKLY_KEEP  = 4;
@@ -23,8 +24,29 @@ function gh(args, opts = {}) {
     return r.stdout;
 }
 
+// Synchronous sleep; the script is intentionally spawnSync-based.
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// The GitHub API occasionally answers 5xx; retry a few times and otherwise
+// skip the prune - missing one night is harmless, the next run catches up.
+const LIST_ATTEMPTS = 3;
+const RETRY_PAUSE_MS = 10_000;
+
 function listNightlies() {
-    const out = gh(['release', 'list', '--limit', '200', '--json', 'tagName,createdAt,isPrerelease']);
+    let out = null;
+    for (let attempt = 1; attempt <= LIST_ATTEMPTS; attempt++) {
+        try { out = gh(['release', 'list', '--limit', '200', '--json', 'tagName,createdAt,isPrerelease']); break; }
+        catch (e) {
+            console.error(`warning: listing releases failed (attempt ${attempt}/${LIST_ATTEMPTS}): ${e.message}`);
+            if (attempt < LIST_ATTEMPTS) sleep(RETRY_PAUSE_MS);
+        }
+    }
+    if (out === null) {
+        console.error('warning: could not list releases; skipping prune.');
+        return [];
+    }
     let all;
     try { all = JSON.parse(out); }
     catch (e) {
@@ -95,7 +117,11 @@ export function planRetention(releases, opts = {}) {
     const keep     = new Set();
 
     // --- Son: N newest releases -----------------------------------------
-    const sonSlice = releases.slice(0, dailyN);
+    // INVARIANT: the newest nightly is ALWAYS kept (hence max(1, …)). The
+    // next nightly's release notes measure their delta from the nearest tag
+    // (update-changelog.mjs), so deleting the newest tag would silently widen
+    // the next delta and re-report already-published changes.
+    const sonSlice = releases.slice(0, Math.max(1, dailyN));
     for (const r of sonSlice) keep.add(r.tag);
     const sonWeeks  = new Set(sonSlice.map(r => isoWeekKey(r.date)));
     const sonMonths = new Set(sonSlice.map(r => r.iso.slice(0, 7)));
@@ -135,8 +161,10 @@ export function planRetention(releases, opts = {}) {
 }
 
 // --- Entry point -------------------------------------------------------------
-// Skipped when imported as a module (for tests).
-if (import.meta.url === `file://${process.argv[1]}` || import.meta.url.endsWith(process.argv[1]?.replace(/\\/g,'/'))) {
+// Skipped when imported as a module (for tests). pathToFileURL handles Windows
+// separators AND percent-encodes blanks, so the comparison also holds for
+// working copies living in paths with spaces.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     main();
 }
 function main() {

.github/workflows/scripts/update-changelog.mjs

@@ -1,12 +1,21 @@
 // Maintains CHANGELOG.md. Invoked from the nightly and release workflows.
 //
 // Usage:
-//   node .github/workflows/scripts/update-changelog.mjs --nightly          # "## Nightly YYYY-MM-DD (<version>)"
-//   node .github/workflows/scripts/update-changelog.mjs --release v1.2.3   # "## v1.2.3 (YYYY-MM-DD)"
+//   node .github/workflows/scripts/update-changelog.mjs --nightly --notes-only  # "## Nightly YYYY-MM-DD (<version>)"
+//   node .github/workflows/scripts/update-changelog.mjs --release v1.2.3        # "## v1.2.3 (YYYY-MM-DD)"
+//
+// Flags:
+//   --notes <file>   write the release-notes body (section minus header) there
+//   --notes-only     generate notes but do NOT touch CHANGELOG.md — used by
+//                    nightly.yml, which never commits the changelog (only
+//                    release.yml does), so writing it would be a dead write
+//   --version X.Y.Z  decorates the nightly header
 //
 // Commit subject conventions (see bucketize() below):
 //   + Added  * Changed  # Fixed  - Removed  ! TODO
-// Anything else goes into "Other".
+// Anything else goes into "Other". The workflow's own changelog-refresh
+// commits ("* update changelog for vyyyyMMdd") are bookkeeping, not change —
+// they are filtered out entirely (see isChangelogCommit()).
 
 import fs   from 'node:fs';
 import path from 'node:path';
@@ -42,6 +51,14 @@ const PREFIX_TO_BUCKET = {
     '!': 'TODO',
 };
 
+// The release workflow's own bookkeeping commit ("* update changelog for
+// vyyyyMMdd [skip ci]"). It must never appear in notes: even though release.yml
+// tags the release ON that commit, a manual tag or a resurrected history could
+// still leak it into a later range — so the generator filters it defensively.
+export function isChangelogCommit(subject) {
+    return /^\*\s*update changelog for v\d{8}\b/.test(subject || '');
+}
+
 export function bucketize(commits) {
     const buckets = Object.fromEntries(BUCKET_ORDER.map(b => [b, []]));
     for (const c of commits) {
@@ -89,8 +106,10 @@ export function prependSection(existing, section) {
 // ---------------------------------------------------------------------------
 // Git helpers (used when invoked as a script)
 // ---------------------------------------------------------------------------
-function gitLastTag() {
-    const r = spawnSync('git', ['describe', '--tags', '--abbrev=0'], { encoding: 'utf8' });
+function gitLastTag(matchPattern) {
+    const args = ['describe', '--tags', '--abbrev=0'];
+    if (matchPattern) args.push(`--match=${matchPattern}`);
+    const r = spawnSync('git', args, { encoding: 'utf8' });
     if (r.status !== 0) return null;
     return (r.stdout || '').trim() || null;
 }
@@ -119,21 +138,27 @@ function main() {
     let tag  = null;
     let version = null;
     let notesPath = null;       // --notes <file>: write the release-notes body here
+    let notesOnly = false;      // --notes-only: leave CHANGELOG.md untouched
 
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--nightly') { mode = 'nightly'; }
         else if (a === '--release') { mode = 'release'; tag = argv[++i]; }
         else if (a === '--version') { version = argv[++i]; }
         else if (a === '--notes') { notesPath = argv[++i]; }
+        else if (a === '--notes-only') { notesOnly = true; }
     }
     if (!mode) {
-        console.error('usage: update-changelog.mjs --nightly | --release <tag> [--version X.Y.Z.B] [--notes <file>]');
+        console.error('usage: update-changelog.mjs --nightly | --release <tag> [--version X.Y.Z.B] [--notes <file>] [--notes-only]');
         process.exit(2);
     }
 
-    const since   = gitLastTag();
-    const commits = gitCommits(since);
+    // Releases measure from the last STABLE tag (v1.2.3 / vyyyyMMdd) so a
+    // same-day nightly-* tag never swallows the release's commit range.
+    // Nightlies keep the nearest tag of any kind: their notes are the delta
+    // since the previous nightly (or stable, whichever is closer).
+    const since   = gitLastTag(mode === 'release' ? 'v[0-9]*' : null);
+    const commits = gitCommits(since).filter(c => !isChangelogCommit(c.subject));
 
     const header = mode === 'nightly'
         ? `Nightly ${isoToday()}${version ? ` (${version})` : ''}`
@@ -151,6 +176,11 @@ function main() {
         console.log(`Wrote release notes to ${notesPath}.`);
     }
 
+    if (notesOnly) {
+        console.log('--notes-only: CHANGELOG.md left untouched.');
+        return;
+    }
+
     if (commits.length === 0) {
         console.log('No new commits since last tag -- CHANGELOG unchanged.');
         return;
@@ -161,7 +191,8 @@ function main() {
     console.log(`CHANGELOG updated with ${commits.length} commit(s) under "${header}".`);
 }
 
-const invokedPath = process.argv[1] ? process.argv[1].replace(/\\/g, '/') : '';
-if (import.meta.url === `file://${invokedPath}` || import.meta.url.endsWith(invokedPath)) {
+// pathToFileURL handles Windows separators AND percent-encodes blanks, so the
+// comparison also holds for working copies living in paths with spaces.
+if (process.argv[1] && import.meta.url === url.pathToFileURL(process.argv[1]).href) {
     main();
 }