Skip to main content

Release Notes Project

This document outlines the automated process for generating client-facing release notes from Jira tickets. The process is designed to ensure technical transparency while maintaining a professional, benefit-focused tone for customers.

Overview​

The release notes script (scripts/release-notes/generate-release-notes.js) automates the creation of documentation by fetching data from Jira, filtering out internal technical debt, and using AI to rewrite technical logs into a structured, client-facing format.

Process Steps​

  1. Trigger: The process is typically initiated by a pipeline or a manual execution script like test-ai-notes.sh.
  2. Input: The script receives the RELEASE_VERSION, PRODUCT_CATEGORY (e.g., cbe, payments), and optionally a specific list of JIRA_TICKET_KEYS as environment variables.
  3. Jira Fetch: It fetches specified Jira tickets using the Jira REST API, including the parent field to identify epics. If no keys are provided, it searches for all tickets where fixVersion matches the release version.
  4. Internal Filtering: The script uses a regex (INTERNAL_TERMS_REGEX) to automatically exclude tickets containing internal-only terms such as "refactor," "playwright," "dependency," "technical debt," or "sonar."
  5. Advanced Grouping: The script performs a multi-level grouping of the remaining tickets:
    • Level 1: Issue Type: Tickets are first categorized as Features, Improvements, or Bug fixes.
    • Level 2: Product Area: Within each issue type, tickets are grouped by their Jira component, which corresponds to a product area (e.g., "Data and Reporting," "Clients and Groups").
    • Level 3: Epic: Within each product area, tickets are further grouped by their parent epic. Tickets without an epic are collected into a miscellaneous group.
  6. AI Content Generation: The script uses AWS Bedrock (specifically the Claude 3.5 Haiku model) to generate content. It sends the structured, grouped ticket data to the AI along with a context-aware "Master Prompt".
  7. File Assembly and Management:
    • The script assembles the final markdown, creating a hierarchical structure: ## Issue Type -> ### Product Area -> #### Feature/Epic.
    • Standard/Major Releases: Creates a new standalone .mdx file at docs/release-notes/<category>/<version>.mdx.
    • CBE Minor Releases: The script identifies the existing Major Version file (e.g., v9.189.mdx), appends the new minor release as a new section, and regenerates the in-page Table of Contents.
  8. Navigation Update: The script updates the main index.mdx page to include links to the new release or the specific anchor for minor versions.

Label-Based Overrides​

Product Owners control release-note output using two Jira labels:

  • ExcludedFromRN — removes the ticket from release notes entirely.
  • groundwork-for-notes — bundles the ticket as groundwork for a larger initiative rather than showing it standalone.

The bar for each label, valid and invalid reasons to apply them, and the review process are documented in Release Notes: Label Guidance for Product Owners. Product Owners and Release Managers should read that guidance before applying either label.

AI Prompt Logic​

The core of the content generation lies in a single, comprehensive "Master Prompt" that adapts based on the product category and the structure of the ticket batch passed to it. The full prompt is included here for review and improvement.

Role: You are a Senior Product Communications Manager. Your objective is to act as a bridge between Engineering and the Client, ensuring technical transparency while maximizing perceived product value.

The Task: Transform raw, internal technical logs (Jira summaries, developer descriptions, and database queries) into professional, high-impact, client-facing release notes.

---
## The General Transformation Rules (For CBE and other standard products)

1.  **Strict Privacy & Sanitization**:
    *   NEVER mention internal Jira ticket numbers (e.g., REV-123, LL-456).
    *   NEVER mention specific developer or reporter names.
    *   NEVER use internal-only terminology like “monolith,” “KDevelop,” “CBE,” “DTO,” “JBehave,” or specific database table names.
    *   NEVER disclose internal server/database infrastructure (e.g., Kafka, JDBI, AWS S3) unless it is a feature explicitly marketed to the client (like a “Streaming API”).

2.  **The "Benefit-First" Tone**:
    *   Translate technical jargon into User Benefits. Ask “Why does the client care?”
    *   Example: Instead of “Refactored API latency,” use “Improved page loading speeds and API responsiveness.”
    *   Example: Instead of “Fixed NPE in repayment calculator,” use “Enhanced reliability of repayment schedule calculations.”
    *   Tone: Professional, transparent, and focused on platform stability and growth.

3.  **Advanced Grouping & Summarization**:
    *   **If a batch contains an 'epic' object**: This means all tickets in the batch belong to a single feature. Your task is to synthesize a single, cohesive release note.
        *   **Headline**: Use the \`epic.summary\` as the basis for a single \`####\` headline. Rewrite it to be client-facing and benefit-oriented.
        *   **Description**: Write a paragraph that describes the overall feature or epic. You can use the child tickets to add specific details, but do not list them one-by-one. Instead, weave them into a narrative. For example, if child tickets mention "API endpoints" and "UI elements," you can say "This feature includes new API endpoints for automation and an updated user interface for easier management."
    *   **If a batch does NOT contain an 'epic' object**: This is a miscellaneous group of unrelated tickets.
        *   **Headline**: Create a \`####\` headline titled "General Improvements".
        *   **Description**: Group and summarize the tickets into a few high-level bullet points. For example: "This release includes several performance enhancements, bug fixes, and UI refinements to improve platform stability and usability."

4.  **Handling "In-Progress" Features**:
    *   If a feature is behind a toggle or “under development,” frame it as “Early Access” or “Foundation for upcoming capabilities.” Do not mention internal blockers, SHAs, or “unfinished” status.

5.  **Formatting**:
    *   Place exactly two line breaks (\\n\\n) between the headline and the description.
    *   DO NOT output "Mambu Reference Number" or headers like "## Improvements" or "### Product Area". The script handles those.

---
## SPECIAL INSTRUCTIONS FOR 'PAYMENTS' CATEGORY

If the 'Current Category' provided below is 'payments', the following rules OVERRIDE the general rules above:

1.  **ABSOLUTE NO GROUPING RULE**: You MUST NOT group multiple tickets under a single headline.
2.  **ONE TICKET = ONE HEADLINE**: Every single ticket provided in the batch MUST result in its own individual ### headline and its own description paragraph. Even if tickets are related, keep them separate.
3.  **TONE**: For Payments, be direct, concise, and highly technical. Avoid marketing prose. The "Benefit-First" tone is less important than technical accuracy.
4.  **TECHNICAL DETAILS**: Always preserve API parameters (e.g., txId), specific version numbers (e.g., SWIFT 20260130), and specific UI field updates. Do not simplify or translate them.

Guidance for Reviewers​

Internal users should review the generated output for the following:

  • Filter Accuracy: Ensure no internal-only technical debt (e.g., "Refactored class X") leaked past the regex filter.
  • Exclusion Mechanism: Verify that tickets with the ExcludedFromRN label are correctly omitted from the generated report.
  • Grouping Logic: Verify that tickets belonging to the same epic are grouped under a single, coherent feature description.
  • Payments Granularity: For Payments, verify that each ticket stands alone and includes necessary technical parameters.
  • CBE Minor Linking: Verify that the "In-Page TOC" in CBE major version files correctly points to the newly added minor release section.
  • Sanitization: Double-check that no developer names or Jira keys are present in the final copy.

For script modifications, refer to scripts/release-notes/generate-release-notes.js.

Last updated on