MTV - automation of Release Notes

[andydub97]

Automate Release Notes Generation with Python Script

Summary

This PR introduces an automated release notes generation system that streamlines the process of creating release notes documentation from JIRA ticket exports. The solution includes a Python script that handles branch creation, CSV processing, AsciiDoc file generation, and automatic master.adoc updates.

Problem Statement

Creating release notes for MTV/Forklift releases is a manual, time-consuming process that involves:

• Manually creating git branches
• Copying and formatting JIRA ticket information into AsciiDoc files
• Ensuring proper file naming conventions
• Updating master.adoc to include new release notes modules
• Avoiding duplicate entries when updating existing release notes

This PR automates these steps to reduce manual effort and minimize errors.

What This PR Does

Core Functionality

This PR adds a comprehensive Python script (scripts/generate_release_notes.py) that:

1. Automates Git Branch Creation

   • Creates a new branch named MTV-RN-<version> (e.g., MTV-RN-2.11.1)
   • Allows selection of base branch from available git branches
   • Handles existing branches gracefully

2. Processes JIRA CSV Exports

   • Parses CSV files exported from JIRA
   • Auto-detects common column name variations (Issue Key, Summary, Description, Workaround)
   • Handles different CSV delimiters automatically
   • Extracts issue keys, summaries, descriptions, and workarounds

3. Generates AsciiDoc Files

   • Creates release notes header file (rn-{major-version}.adoc)
   • Generates resolved issues file (rn-{version}-resolved-issues.adoc)
   • Generates known issues file (known-issues-{major-version}.adoc)
   • Formats content according to existing AsciiDoc conventions
   • Includes proper JIRA ticket links

4. Intelligent File Management

   • Appends new issues to existing files instead of overwriting
   • Detects and skips duplicate issues based on JIRA ticket keys
   • Preserves existing content when adding new issues
   • Provides clear feedback on what was added vs. what already existed

5. Automatic master.adoc Updates

   • Updates documentation/doc-Release_notes/master.adoc automatically
   • Inserts new release notes modules in the correct locations
   • Maintains proper AsciiDoc include statements with correct level offsets
   • Handles version conflicts gracefully

Key Features

• Version-Agnostic: Works with any MTV version format (2.9.0, 2.10.1, 2.11.1, etc.) - To be tested
• Duplicate Detection: Identifies and skips issues that already exist in files
• Append Mode: Adds new issues to existing release notes without losing data
• CSV Flexibility: Handles various CSV export formats and column name variations
• Error Handling: Provides error messages and handles edge cases
• User-Friendly: Interactive prompts guide users through the process

Files Added

• scripts/generate_release_notes.py - Main Python script (812 lines)
• scripts/README.md - Comprehensive documentation
• scripts/QUICK_START.md - Quick reference guide
• scripts/sample_resolved_issues.csv - Example CSV template for resolved issues
• scripts/sample_known_issues.csv - Example CSV template for known issues

Usage Example

python3 scripts/generate_release_notes.py

The script prompts for:

1. Base branch selection
2. MTV version (e.g., 2.11.1)
3. Path to resolved issues CSV file
4. Path to known issues CSV file

It then:

• Creates branch MTV-RN-2.11.1
• Generates rn-2-11.adoc, rn-2-11-1-resolved-issues.adoc, known-issues-2-11.adoc
• Updates master.adoc with new includes

CSV Format Requirements

The script expects CSV files with these columns (auto-detects variations):

• Issue Key (required): e.g., MTV-3915
• Summary (required): Issue title
• Description (required): Issue description
• Workaround (optional, for known issues): Workaround text

Benefits

1. Time Savings: Reduces release notes creation time from hours to minutes
2. Consistency: Ensures consistent formatting across all release notes
3. Accuracy: Eliminates manual copy-paste errors
4. Safety: Prevents duplicate entries and preserves existing content
5. Maintainability: Standardizes the release notes process
6. Backward Compatible: Works with existing release notes structure

Technical Details

• Language: Python 3.6+
• Dependencies: Standard library only (no external dependencies)
• File Format: AsciiDoc (.adoc)
• Git Operations: Uses subprocess to execute git commands
• CSV Parsing: Uses Python's built-in csv module with auto-delimiter detection

Testing

This PR has been tested with:

• Version format validation
• CSV parsing with various formats
• File append functionality
• Duplicate detection
• master.adoc update logic

The script is not ready for use with any MTV release version until further testing is complete.

Documentation

Comprehensive documentation is included:

• README.md: Full feature documentation, CSV format guide, troubleshooting
• QUICK_START.md: Step-by-step usage guide
• Sample CSV files: Examples showing expected format

Future Enhancements

Potential future improvements:

• Support for new features/enhancements sections
• Integration with JIRA API for direct ticket fetching
• Support for security fixes sections
• Batch processing multiple versions

Known Limitations and Future Work

This PR provides a solid foundation for automating release notes generation, but there are additional workflow considerations:

• RENOA Workflow: A RENOA workflow must be implemented to fully automate the release notes process
• JIRA Workflow Changes: JIRA may need to be modified to include a workflow that incorporates RENOA. This might require adding a new release notes field to track RENOA status
• RENOA API Integration: MMS docs team has requested a meeting with Dan to explore whether a RENOA API can be leveraged for further automation

These enhancements would complement the current script-based approach and potentially enable more direct integration with JIRA and the RENOA system.

[Jenny-Anne]

Suggested change

	- Known issues: `project = MTV AND labels = "known-issue" AND fixVersion = "2.11.1"`
	- Known issues: `project = MTV AND labels = "known-issue" AND fixVersion = "2.11.*"`

[Jenny-Anne]

Hi @anarnold97 I'm not sure if a wildcard like "2.11.*" is an option here in your script, but I know it works in Jira queries. It's just that if a known issue is in a release, it won't have that release as a fix version because the fix is targeted for a later release, e.g. an issue is a known issue in 2.11.1. The fix is targeted for 2.11.3. The Jira won't have 2.11.1 as the fix version. It might have 2.11.3 as the fix version or something like or 2.11.z if the fix version isn't determined yet.

[Jenny-Anne]

One thing to be aware of capturing is known issues that are updated to bug fixes, e.g. an issue might be a known issue for three releases in a row and then be updated to bug fix when it's finally resolved. There's no need to create a separate Jira for the bug fix, just update the release note type and description from known issue to bug fix in the original Jira.

[Jenny-Anne]

Test Jira filter for 2.11: https://issues.redhat.com/issues/?filter=12490270
with test Jira query:
project = "Migration Toolkit for Virtualization" AND "Release Note Type" not in (---, "Release Note Not Required", "CVE - Common Vulnerabilities and Exposures") AND fixVersion = 2.11.1 OR ("Release Note Type" = "Known issue" AND fixVersion ~ "2.11.*")

[Jenny-Anne]

Test 2 Jira filter with AND labels = release-note-req added (optional)
https://issues.redhat.com/issues/?filter=12490271
with test Jira query:
project = "Migration Toolkit for Virtualization" AND labels = release-note-req AND "Release Note Type" not in (---, "Release Note Not Required", "CVE - Common Vulnerabilities and Exposures") AND fixVersion = 2.11.1 OR ("Release Note Type" = "Known issue" AND fixVersion ~ "2.11.*")