Add HEAD fallback

Author: Rundeck CI

README.md

@@ -167,6 +167,12 @@ cat docs/history/5_x/draft.md
 npm run notes -- --milestone=5.17.0
 ```
 
+**Tag Detection:**
+- If the tag exists (e.g., `v5.17.0`), draft mode uses the exact tag comparison
+- If the tag doesn't exist yet, draft mode automatically uses `HEAD` to preview what will be in the release
+  - You'll see: "Warning: Tag 5.17.0 not found, using HEAD for preview"
+  - This allows you to preview release notes before creating the tag
+
 ## What the Script Does
 
 When you run `npm run notes -- --milestone=5.17.0`, it will:
@@ -191,19 +197,25 @@ When you run `npm run notes -- --milestone=5.17.0`, it will:
 ### Self-Hosted Release Process
 
 ```bash
-# 1. Generate draft for review
+# 1. Generate draft for review (before tagging)
+# If tag doesn't exist yet, uses HEAD for preview
 npm run notes:draft -- --milestone=5.17.0
 
 # 2. Review the generated draft
 code docs/history/5_x/draft.md
 
-# 3. Generate final release notes (updates all configs)
+# 3. Create the version tag
+git tag v5.17.0
+git push origin v5.17.0
+
+# 4. Generate final release notes (updates all configs)
+# Now uses the exact tag for accurate PR detection
 npm run notes -- --milestone=5.17.0
 
-# 4. Edit the generated file for dates, overview, etc.
+# 5. Edit the generated file for dates, overview, etc.
 code docs/history/5_x/version-5.17.0.md
 
-# 5. Commit all changes
+# 6. Commit all changes
 git add docs/history/5_x/version-5.17.0.md
 git add docs/.vuepress/sidebar-menus/history.ts
 git add docs/.vuepress/navbar-menus/about.js
@@ -214,6 +226,8 @@ git commit -m "Release notes for 5.17.0"
 git push
 ```
 
+**Note:** You can preview with draft mode before creating the tag. Draft mode will use HEAD if the tag doesn't exist yet.
+
 ## SaaS Development Updates Feed
 
 For generating RSS/Atom feeds and markdown pages showing recent PRs deployed to the SaaS platform (but not yet in self-hosted releases), see [PR-FEED-README.md](./PR-FEED-README.md).
@@ -228,16 +242,26 @@ The feed date range is automatically updated when you create release notes - no
 
 ## Troubleshooting Release Notes
 
-### "Tags for versions X...Y not found"
+### "Tag X.Y.Z not found" Warning or Error
+
+**In Draft Mode:**
+- Shows warning: "Tag 5.18.0 not found, using HEAD for preview"
+- Uses HEAD (main branch) to preview PRs
+- This is normal before the tag is created
+
+**In Final Mode:**
+- Shows error: "Tag 5.18.0 not found. Create the tag first or use --draft mode."
+- Creates a placeholder file with minimal content
+- Re-run after creating the tag to populate with actual PRs
 
-**Cause**: Tag doesn't exist in the repository or uses different naming.
+**Solution:**
+1. Use draft mode to preview: `npm run notes:draft -- --milestone=5.18.0`
+2. Create the tag when ready: `git tag v5.18.0 && git push origin v5.18.0`
+3. Generate final notes: `npm run notes -- --milestone=5.18.0`
 
-**Solution**:
-- For `docs` and `ansible-plugin` repos: This is normal (they don't use version tags)
-- For main repos: Verify tags exist:
-  ```bash
-  git ls-remote --tags https://github.com/rundeck/rundeck | grep 5.17
-  ```
+**For repo-specific warnings** (`docs`, `ansible-plugin`):
+- This is normal - these repos don't use version tags
+- They'll be skipped gracefully
 
 ### "GH_API_TOKEN environment variable is not set"
 

docs/.vuepress/notes.mjs

@@ -64,12 +64,59 @@ async function main() {
   console.log('=== Rundeck Release Notes Generator ===\n');
   console.log(`Comparing versions: ${fromVersion} → ${toVersion}\n`);
 
+  // Check if toVersion tag exists by attempting to fetch from main repos
+  const gh = new Octokit({ auth: process.env.GH_API_TOKEN });
+  let tagExists = false;
+  let useHead = false;
+  
+  // Try to find the tag in rundeck repo (main repo)
+  const tagFormats = [`v${toVersion}`, toVersion, `V${toVersion}`];
+  for (const tag of tagFormats) {
+    try {
+      await gh.rest.repos.getReleaseByTag({
+        owner: 'rundeck',
+        repo: 'rundeck',
+        tag: tag
+      });
+      tagExists = true;
+      break;
+    } catch (error) {
+      if (error.status !== 404) {
+        // Some other error, try git refs
+        try {
+          await gh.rest.git.getRef({
+            owner: 'rundeck',
+            repo: 'rundeck',
+            ref: `tags/${tag}`
+          });
+          tagExists = true;
+          break;
+        } catch (refError) {
+          // Continue to next format
+        }
+      }
+    }
+  }
+  
+  // Determine behavior based on tag existence and mode
+  if (!tagExists) {
+    if (argv.draft) {
+      console.log(`\nWarning: Tag ${toVersion} not found, using HEAD for preview\n`);
+      useHead = true;
+    } else {
+      console.error(`\nERROR: Tag ${toVersion} not found.`);
+      console.error(`       Create the tag first or use --draft mode to preview with HEAD.\n`);
+      console.log(`Continuing with empty results to create placeholder file...\n`);
+      // Continue execution but with empty results
+    }
+  }
+  
   const context = {};
-  context.core = await getRepoData({ repo: 'rundeck', owner: 'rundeck' }, fromVersion, toVersion, ['release-notes/include']);
-  context.enterprise = await getRepoData({ repo: 'rundeckpro', owner: 'rundeckpro' }, fromVersion, toVersion, ['release-notes/include']);
-  context.docs = await getRepoData({ repo: 'docs', owner: 'rundeck' }, fromVersion, toVersion, []); // No label filtering for docs (need all PRs for contributors)
-  context.ansible = await getRepoData({ repo: 'ansible-plugin', owner: 'rundeck-plugins' }, fromVersion, toVersion, ['release-notes/include']);
-  context.runner = await getRepoData({ repo: 'sidecar', owner: 'rundeckpro' }, fromVersion, toVersion, ['release-notes/include']);
+  context.core = await getRepoData({ repo: 'rundeck', owner: 'rundeck' }, fromVersion, toVersion, ['release-notes/include'], useHead);
+  context.enterprise = await getRepoData({ repo: 'rundeckpro', owner: 'rundeckpro' }, fromVersion, toVersion, ['release-notes/include'], useHead);
+  context.docs = await getRepoData({ repo: 'docs', owner: 'rundeck' }, fromVersion, toVersion, [], useHead); // No label filtering for docs (need all PRs for contributors)
+  context.ansible = await getRepoData({ repo: 'ansible-plugin', owner: 'rundeck-plugins' }, fromVersion, toVersion, ['release-notes/include'], useHead);
+  context.runner = await getRepoData({ repo: 'sidecar', owner: 'rundeckpro' }, fromVersion, toVersion, ['release-notes/include'], useHead);
   context.contributors = { ...context.core.contributors, ...context.docs.contributors, ...context.ansible.contributors };
 
   context.version = new RundeckVersion({ versionString: argv.milestone });
@@ -188,12 +235,15 @@ function updateNavbarReleaseLink(version) {
   }
 }
 
-async function getRepoData(repo, fromVersion, toVersion, includeLabels) {
+async function getRepoData(repo, fromVersion, toVersion, includeLabels, useHead = false) {
   const gh = new Octokit({ auth: process.env.GH_API_TOKEN });
 
   console.log(`Fetching PRs from ${repo.owner}/${repo.repo}...`);
 
   try {
+    // Determine the head reference
+    const headRef = useHead ? 'main' : null;
+    
     // Fetch PRs between tags using shared utility
     const pulls = await fetchPRsBetweenTags(
       gh,
@@ -202,7 +252,8 @@ async function getRepoData(repo, fromVersion, toVersion, includeLabels) {
       fromVersion,
       toVersion,
       includeLabels,
-      excludeUsernames // Use excludeUsernames as exclude labels (though these are for contributors)
+      excludeUsernames, // Use excludeUsernames as exclude labels (though these are for contributors)
+      headRef
     );
 
     // Extract contributors (excluding bots and internal users)