Migration from Milestone-based to Tag-based Release Notes

[fdevans]

Migrate Release Notes Generation from Milestone-based to Tag-based Approach

Overview

This PR updates the notes.mjs script to use git tag comparison instead of GitHub milestones for collecting Pull Requests in release notes generation. This aligns with the approach already used in pr-feed.mjs and provides more accurate PR detection based on actual git history.

What Changed

Before (Milestone-based)

• Used GitHub API to find PRs tagged with a specific milestone
• Required manual milestone assignment for each PR
• Could miss PRs if milestones weren't properly set
• Different approach from pr-feed.mjs

After (Tag-based)

• Compares two git tags to find all commits between releases
• Automatically discovers PRs from merge commits (including squash and rebase merges)
• No manual milestone tagging required
• Consistent with pr-feed.mjs approach
• More accurate - captures ALL changes in git history between releases

Files Changed

New Files

• docs/.vuepress/pr-utils.mjs - Shared utility functions for both notes.mjs and pr-feed.mjs
  • fetchPRsBetweenTags() - Compare two git tags to find all PRs
  • extractPRSection() - Extract specific sections from PR bodies
  • cleanPRTitle() - Remove RUN-XXXX prefixes
  • parseSaasCutTag() - Parse SaaS cut tag format
  • getPreviousVersion() - Auto-decrement version numbers

Modified Files

• docs/.vuepress/notes.mjs - Now uses tag-based comparison and shared utilities

  • Added --from-version argument for custom version ranges
  • Auto-detects previous version (e.g., 5.17.0 → 5.16.0)
  • Uses shared functions from pr-utils.mjs
  • Gracefully skips repos without tags

• docs/.vuepress/pr-feed.mjs - Refactored to use shared utilities

  • Removed duplicate code
  • Now imports from pr-utils.mjs
  • Maintains backward compatibility

• package.json - Added new npm script

  • Added notes:draft for generating draft release notes

• README.md - Comprehensive documentation updates

  • Updated release notes generation instructions
  • Added tag-based approach explanation
  • Added version auto-detection table
  • Added typical workflow examples
  • Updated PR labeling guidance (both repos use release-notes/include)
  • Added troubleshooting section

• PR-FEED-README.md - Added shared utilities documentation

  • Documented shared functions with notes.mjs
  • Added related documentation links

Key Benefits

1. Accuracy: Captures all PRs between releases based on actual git history
2. Automation: No need to manually assign milestones to PRs
3. Consistency: Both scripts now use the same tag-based approach
4. Flexibility: Easy to generate notes for any version range
5. Resilience: Handles all merge strategies (merge commits, squash merges, rebase merges)
6. Code Reuse: Shared utilities reduce duplication and ensure consistent behavior
7. Preview Capability: Draft mode can preview release notes before tag is created (uses HEAD)

Version Auto-Detection

The script automatically decrements the version to find the previous release:

Target Version	Auto-detected Previous	What it compares
5.17.0	5.16.0	v5.16.0 → v5.17.0
5.17.1	5.17.0	v5.17.0 → v5.17.1
5.0.0	4.17.0	v4.17.0 → v5.0.0

Override with --from-version for custom ranges.

New Usage

Basic Usage (recommended)

# Auto-detects previous version (5.17.0 → 5.16.0)
npm run notes -- --milestone=5.17.0

# Generate draft for testing (doesn't update configs)
npm run notes:draft -- --milestone=5.17.0

# Custom version range (for patch releases)
npm run notes -- --milestone=5.17.1 --from-version=5.17.0

Direct Script Usage

node ./docs/.vuepress/notes.mjs --milestone=5.17.0
node ./docs/.vuepress/notes.mjs --milestone=5.17.0 --draft
node ./docs/.vuepress/notes.mjs --milestone=5.17.1 --from-version=5.17.0

Testing

Tested by comparing output from tag-based approach with the existing version-5.17.0.md:

Results

• Contributors: Identical results between both approaches
• PRs Found: Tag-based approach found 4 additional PRs that were merged but not assigned to the milestone:
  • 2 additional enterprise PRs (RSS feed fix, CVE fix)
  • 2 additional open source PRs (proxy fix, CVE fix)
• Accuracy: Tag-based approach is more comprehensive

Test Commands Used

# Generate draft and compare
npm run notes:draft -- --milestone=5.17.0
diff docs/history/5_x/draft.md docs/history/5_x/version-5.17.0.md

Breaking Changes

The script no longer uses GitHub milestones.

• PRs are now discovered via git tag comparison
• The --milestone argument is still required but now represents the target version (not a GitHub milestone name)
• Any workflows depending on milestone-based detection need to be updated

Graceful Handling

Tag Not Found Behavior

Draft Mode (--draft):

• If the target version tag doesn't exist, automatically uses HEAD for preview
• Allows previewing release notes before creating the tag
• Shows warning: "Tag X.Y.Z not found, using HEAD for preview"

Final Mode:

• If the target version tag doesn't exist, shows error message
• Creates placeholder file with minimal content
• Still updates all configuration files
• Re-run after creating tag to populate with actual PRs

Repository-Specific Tag Handling

• Repositories without version tags (e.g., docs, ansible-plugin) are gracefully skipped with warnings
• Contributors from other repos are still collected
• The script continues processing even if some repos don't have tags

Environment Requirements

Requires .env file with GitHub token:

GH_API_TOKEN=ghp_your_actual_token_here

Token needs access to:

• rundeck/rundeck (public)
• rundeckpro/rundeckpro (private)
• rundeck/docs (public)
• rundeck-plugins/ansible-plugin (public)
• rundeckpro/sidecar (private)

Documentation Updates

• README.md: Complete rewrite of release notes section with tag-based approach
• PR-FEED-README.md: Added shared utilities documentation
• Both files updated to remove emojis (per copilot-instructions)
• PR labeling guidance updated to reflect current approach

Typical Workflow (Updated)

# 1. Merge all PRs for the release

# 2. Generate draft for review (before tagging)
# If tag doesn't exist, automatically uses HEAD for preview
npm run notes:draft -- --milestone=5.17.0
# Output: "Warning: Tag 5.17.0 not found, using HEAD for preview"

# 3. Review the generated draft
cat docs/history/5_x/draft.md

# 4. Create the version tag
git tag v5.17.0
git push origin v5.17.0

# 5. Generate final release notes (updates all configs)
# Now uses exact tag comparison for accuracy
npm run notes -- --milestone=5.17.0

# 6. Edit for dates, overview, etc.
code docs/history/5_x/version-5.17.0.md

# 7. Commit changes
git add docs/history/5_x/version-5.17.0.md
git add docs/.vuepress/
git commit -m "Release notes for 5.17.0"

Backward Compatibility Note

The npm scripts remain the same - npm run notes still works. The underlying implementation now uses tags instead of milestones, providing better accuracy without changing the user interface.

Related Issues

Resolves issues with:

• Missing PRs in release notes due to forgotten milestone assignments
• Inconsistent approaches between notes.mjs and pr-feed.mjs
• Manual milestone management overhead

[Copilot]

Pull Request Overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.