Release Notes Creation Documentation

Overview

The release.go script now supports a --create-release-notes flag that extracts changelog content from UNRELEASED_CHANGELOG.md and creates a clean release_notes.md file suitable for GitHub releases.

How It Works

1. Command Usage

go run release.go --create-release-notes [output_path]

• output_path is optional, defaults to ../../release_notes.md
• The script expects UNRELEASED_CHANGELOG.md to be at ../../UNRELEASED_CHANGELOG.md (relative to the script location)

2. Extraction Process

The extractChangelogContent() function:

1. Reads the UNRELEASED_CHANGELOG.md file
2. Filters out:
   • The main "# Unreleased Changes" header
   • HTML comments (<!-- ... -->)
   • Empty sections (sections with no bullet points)
   • Everything after the --- separator (example entries)
3. Preserves:
   • Section headers (## Added, ## Changed, etc.) that have content
   • Bullet points with actual text (both - and * styles)
   • Proper spacing between sections

3. File Structure Expected

# Unreleased Changes

<!-- Comments are ignored -->

## Added
<!-- Section comments ignored -->
- Actual content preserved
- More content

## Changed
<!-- Empty sections are omitted -->

## Fixed
- Bug fixes included

---

### Example Entries:
Everything after the --- is ignored

4. Output Format

The generated release_notes.md contains only the actual changelog entries:

## Added
- Actual content preserved
- More content

## Fixed
- Bug fixes included

Testing Results

✅ Successful Tests

1. Valid Content Extraction: Successfully extracts and formats changelog entries
2. Empty Changelog Detection: Properly fails when no content exists
3. Comment Filtering: Correctly removes HTML comments
4. Mixed Bullet Styles: Handles both - and * bullet points
5. Custom Output Path: Supports specifying custom output file location
6. Flag Compatibility: Works with --check-only and --extract-changelog flags

Test Commands Run

# Create release notes with default path
go run release.go --create-release-notes

# Create with custom path
go run release.go --create-release-notes /path/to/output.md

# Check if content exists
go run release.go --check-only

# Extract content to stdout
go run release.go --extract-changelog

Integration with GitHub Workflow

The nightly release workflow should:

1. Run go run release.go --create-release-notes before the main release task
2. Use the generated release_notes.md for the GitHub release body
3. The main release task will clear UNRELEASED_CHANGELOG.md after processing

Error Handling

The script will exit with status 1 if:

• UNRELEASED_CHANGELOG.md doesn't exist
• No actual content is found (only template/comments)
• File write operations fail

Benefits

1. Separation of Concerns: Changelog extraction happens before the file is cleared
2. Clean Output: No template text or comments in release notes
3. Testable: Can be run and tested independently
4. Flexible: Supports custom output paths
5. Consistent: Same extraction logic used by all flags