Refine release notes generation context

Use GitHub release notes plus commit data so direct-push
changes are included, and update the prompt to dedupe and
reference commits or PRs consistently.

Author: mcowger

.github/workflows/prompts/release-generate-notes.md

@@ -1,15 +1,32 @@
 Generate release notes for version ${{ inputs.tag }}.
-Read the file `github_changes.tmp.json` in the current directory. It contains an array
-of commits between the previous and current release tags, each with:
-- sha: the commit SHA
-- fullMessage: the full commit message (multiline)
-- shortMessage: the first line of the commit message
-- author: the commit author name
-- date: the commit date (ISO 8601)
-- url: the commit URL on GitHub
-- pr: the associated PR info (number, title, body, url, author, labels, merged_at) or null if directly committed
-
-Use ONLY this data — do not look up additional history.
+
+Read the file `github_changes.tmp.json` in the current directory. It has this shape:
+
+```json
+{
+  "current_tag": "YYYY.MM.DD.N",
+  "previous_tag": "YYYY.MM.DD.N",
+  "github_generated_notes": "<markdown string from GitHub's generate-notes API>",
+  "commits": [
+    {
+      "sha": "<short sha>",
+      "message": "<first line of commit message>",
+      "author": "<name>",
+      "date": "<ISO 8601>",
+      "url": "<commit URL>"
+    }
+  ]
+}
+```
+
+**Two sources, both equally important:**
+
+- `github_generated_notes` — A markdown list of **merged PRs** in this release, generated server-side by GitHub. This is the authoritative source for changes that came in via pull request.
+- `commits` — Every commit in the range between the previous and current tag. This is the authoritative source for **direct-push changes** (commits not associated with a PR). Many real changes land this way.
+
+**Deduplication:** A commit and a PR entry may describe the same change (e.g., a PR merge commit). When they clearly refer to the same thing, include it once — prefer the PR entry since it has richer metadata (number, author). Do not list a change twice.
+
+Use ONLY data from these two sources — do not look up additional history.
 
 ---
 
@@ -33,23 +50,24 @@ The release notes must follow this structure, in this order, with no additional
    backwards-incompatible changes. Each bullet should:
    - Clearly state what changed and what the impact is
    - Link to a migration guide or workaround if one exists
-   - Reference the PR or issue number in parentheses at the end
+   - Reference the PR or issue number in parentheses at the end, or the commit SHA if no PR exists
    If there are NO breaking changes, omit this entire section entirely. Do not include the heading with an empty list.
 
-5. **New Features** — An H3 section (🆕 icon) listing new capabilities. Each bullet should:
+5. **New Features** — An H3 section (✨ icon) listing new capabilities. Each bullet should:
    - Bold the feature name, followed by an em dash, then a one-sentence description
-   - Reference the PR or issue number in parentheses at the end
-   - Example: **Feature Name** — Description of the feature. (#1234)
+   - Reference the PR number in parentheses at the end, or the short commit SHA if no PR exists
+   - Example (PR): **Feature Name** — Description of the feature. (#1234)
+   - Example (direct push): **Feature Name** — Description of the feature. (abc1234)
 
 6. **Bug Fixes** — An H3 section (🐛 icon) listing resolved issues. Each bullet should:
    - Start with "Fixed", "Resolved", or "Corrected"
    - Briefly describe the bug and its fix
-   - Reference the PR or issue number in parentheses at the end
+   - Reference the PR number or commit SHA in parentheses at the end
    - Example: Fixed an issue where [description of bug]. (#5678)
 
-7. **Other Changes** — An H3 section (📦 icon) for deprecations, notable internal improvements, or anything that doesn't fit above, but only when it is meaningful to end users, operators, or integrators. Do NOT include items that are purely dependency updates or purely CI/workflow/build-pipeline maintenance. Same bullet format as the other sections.
+7. **Other Changes** — An H3 section (🔧 icon) for deprecations, notable internal improvements, or anything that doesn't fit above, but only when it is meaningful to end users, operators, or integrators. Do NOT include items that are purely dependency updates or purely CI/workflow/build-pipeline maintenance. Same bullet format as the other sections.
 
-8. **Contributors** — An H3 section (🙏 icon) listing the people who contributed, prefixed with @. Format as a comma-separated line:
+8. **Contributors** — An H3 section (👥 icon) listing the people who contributed, prefixed with @. Format as a comma-separated line:
    Thanks to the following people who contributed to this release:
    @username1, @username2, @username3
 
@@ -60,10 +78,11 @@ The release notes must follow this structure, in this order, with no additional
 - Do NOT add sections not listed above (no Upgrade Instructions, no Links, no FAQ, etc.).
 - Breaking Changes comes immediately after Overview, before New Features.
 - If a section has no items, omit the section and its heading entirely — do not leave an empty section.
-- Exclude changes that are purely dependency/version bumps, lockfile refreshes, package manager maintenance, or similar dependency housekeeping unless the input clearly shows a user-visible impact that should be called out.
-- Exclude changes that are purely CI, GitHub Actions, workflow, release automation, test harness, or build-pipeline maintenance unless the input clearly shows a user-visible operational impact that belongs in release notes.
-- If a PR or commit mixes substantive product changes with dependency or CI/workflow churn, include only the substantive product-facing change and ignore the maintenance-only parts.
-- Every bullet must end with a PR or issue number in parentheses, e.g. (#1234), unless the input provides none.
+- Treat direct-push commits as full equals to PR-based changes — do not bury or omit them because they lack a PR number.
+- Exclude changes that are purely dependency/version bumps, lockfile refreshes, or package manager maintenance unless there is a clear user-visible impact.
+- Exclude changes that are purely CI, GitHub Actions, workflow, release automation, test harness, or build-pipeline maintenance unless there is a clear user-visible operational impact.
+- If a PR or commit mixes substantive product changes with dependency or CI/workflow churn, include only the substantive product-facing change.
+- Every bullet must end with a PR number (#NNN) or short commit SHA in parentheses. Only omit a reference if the input provides absolutely none.
 - Keep the narrative overview concise (3-5 sentences). It should read like a human wrote it, not an automated log.
 - Use consistent tense: present tense for features ("Adds"), past tense for fixes ("Fixed").
-- Do not use the header divider (---) between sections; only use it after the title/date block and after the overview.
+- Do not use the header divider (---) between sections; only use it after the title/date block and after the overview.

.github/workflows/release-generate-notes.yml

@@ -22,75 +22,88 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           fetch-depth: 0
 
-      - name: Get previous release tag
-        id: prev_tag
-        run: |
-          CURRENT_TAG="${{ inputs.tag }}"
-          CURRENT_SHA=$(git rev-parse "${CURRENT_TAG}^{}")
-          CURRENT_DATE=$(git log -1 --format=%ci "${CURRENT_SHA}")
-
-          PREV_TAG=""
-          for tag in $(git tag --sort=-creatordate --list "[0-9]*.[0-9]*.[0-9]*.[0-9]*" "v*.*.*" 2>/dev/null); do
-            if [ "$tag" = "$CURRENT_TAG" ]; then continue; fi
-            tag_sha=$(git rev-parse "${tag}^{}" 2>/dev/null || true)
-            [ -z "$tag_sha" ] && continue
-            tag_date=$(git log -1 --format=%ci "${tag_sha}")
-            if [ "$tag_date" '<' "$CURRENT_DATE" ]; then
-              PREV_TAG="$tag"
-              break
-            fi
-          done
-
-          echo "Previous release tag: $PREV_TAG"
-          echo "tag=$PREV_TAG" >> "$GITHUB_OUTPUT"
-          echo "current_tag=$CURRENT_TAG" >> "$GITHUB_OUTPUT"
-          echo "current_sha=$CURRENT_SHA" >> "$GITHUB_OUTPUT"
-          if [ -n "$PREV_TAG" ]; then
-            echo "prev_sha=$(git rev-parse "${PREV_TAG}^{}")" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Gather commits and PR info
-        id: commits
+      - name: Gather release context via GitHub API
+        id: context
         uses: actions/github-script@v9
         with:
           script: |
-            const { data: comparison } = await github.rest.repos.compareCommits({
+            const currentTag = '${{ inputs.tag }}';
+
+            // ── 1. Find the previous CalVer release using GitHub's Releases API ──
+            // This is immune to git history rewrites/rebases: GitHub tracks releases
+            // as server-side objects keyed by publish time, not by git ancestry.
+            const calverRe = /^\d{4}\.\d{2}\.\d{2}\.\d+$/;
+
+            const { data: releases } = await github.rest.repos.listReleases({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              base: '${{ steps.prev_tag.outputs.tag }}',
-              head: '${{ steps.prev_tag.outputs.current_tag }}'
+              per_page: 100,
             });
 
-            const results = [];
-            for (const commit of comparison.commits) {
-              const sha = commit.sha;
-              const fullMessage = commit.commit.message;
-              const shortMessage = fullMessage.split('\n')[0];
-              const author = commit.commit.author.name;
-              const date = commit.commit.author.date;
-              const url = commit.html_url;
+            const calverReleases = releases
+              .filter(r => calverRe.test(r.tag_name) && !r.draft)
+              .sort((a, b) => new Date(b.published_at) - new Date(a.published_at));
 
-              const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                commit_sha: sha
-              });
+            const currentIdx = calverReleases.findIndex(r => r.tag_name === currentTag);
+            const prevRelease = currentIdx >= 0 ? calverReleases[currentIdx + 1] : null;
+            const prevTag = prevRelease?.tag_name ?? null;
+
+            core.info(`Current tag: ${currentTag}`);
+            core.info(`Previous release tag: ${prevTag ?? '(none — first release)'}`);
+
+            // ── 2. Call generate-notes: GitHub tracks PR merges server-side, so
+            //    this is correct even when commits were rebased/force-pushed. ──
+            const notesParams = {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              tag_name: currentTag,
+            };
+            if (prevTag) notesParams.previous_tag_name = prevTag;
 
-              const pr = prs[0] ? {
-                number: prs[0].number,
-                title: prs[0].title,
-                body: prs[0].body,
-                url: prs[0].html_url,
-                author: prs[0].user?.login,
-                labels: prs[0].labels?.map(l => l.name) || [],
-                merged_at: prs[0].merged_at
-              } : null;
+            const { data: generated } = await github.rest.repos.generateReleaseNotes(notesParams);
+            core.info(`generate-notes body length: ${generated.body.length}`);
 
-              results.push({ sha, fullMessage, shortMessage, author, date, url, pr });
+            // ── 3. Get commits via compareCommits for the direct-push context ──
+            // compareCommits uses merge-base, which may include rebased duplicates,
+            // but Claude is instructed to use the PR list as the authoritative source
+            // and treat commits only as supplementary detail for non-PR changes.
+            let commits = [];
+            if (prevTag) {
+              try {
+                const { data: comparison } = await github.rest.repos.compareCommits({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  base: prevTag,
+                  head: currentTag,
+                });
+                commits = comparison.commits.map(c => ({
+                  sha: c.sha.slice(0, 7),
+                  message: c.commit.message.split('\n')[0],
+                  author: c.commit.author.name,
+                  date: c.commit.author.date,
+                  url: c.html_url,
+                }));
+              } catch (e) {
+                core.warning(`compareCommits failed: ${e.message} — proceeding without commit list`);
+              }
             }
 
+            // ── 4. Write context file for Claude ──
             const fs = require('fs');
-            fs.writeFileSync('${{ github.workspace }}/github_changes.tmp.json', JSON.stringify(results, null, 2));
+            const ctx = {
+              current_tag: currentTag,
+              previous_tag: prevTag,
+              // PR-based changes: generated server-side by GitHub, immune to git rebases.
+              // Authoritative for anything that came in via pull request.
+              github_generated_notes: generated.body,
+              // Commit-based changes: all commits in the tag range.
+              // Authoritative for direct-push changes (no PR). Many real changes land
+              // this way. May overlap with PRs above — deduplicate by message when both
+              // describe the same change, preferring the PR entry.
+              commits,
+            };
+            fs.writeFileSync('${{ github.workspace }}/github_changes.tmp.json', JSON.stringify(ctx, null, 2));
+            core.info(`Wrote context file. ${commits.length} commits, prev tag: ${prevTag}`);
 
       - name: Generate release notes via Claude
         id: claude
@@ -122,4 +135,4 @@ jobs:
         with:
           name: release-notes
           path: ${{ runner.temp }}/release-notes/notes.md
-          retention-days: 1
+          retention-days: 1