Skip to main content

​
Creating Release Notes from Jira

​
Quick Start

​
Step 1: Generate Rich Template

node scripts/jira-to-rich-release-notes.js --jql "project IN (CORE, 'AI Integration', 'Rendering Product Team', 'MVP Team', Plugins, 'Platform Team', Documentation) AND fixVersion = 5.2 ORDER BY priority DESC" > release-notes/v5.x/v5.2.0-november-2025/v5.2.0-november-2025.mdx

​
Step 2: Customize the Template

The generated template includes:
  • ✅ Correct MDX structure matching v5.1.1 and v5.2.0 format
  • ✅ Thematic tabs (Features & UX, Platform & Infrastructure, etc.)
  • ✅ Feature cards with nested tabs
  • ✅ All Jira issues organized by theme
  • ✅ TODO markers for where to add rich content

​
Step 3: Fill in Rich Content

Search for <!-- TODO: markers and add:
  1. Overview sections: Detailed feature descriptions
  2. Key Features: CardGroups with feature highlights
  3. Benefits: Business value and use cases
  4. Screenshots/Videos: Add Frame components with images
  5. Code examples: Add syntax-highlighted code blocks

​
File Structure

release-notes/v5.x/v5.2.0-november-2025/
├── v5.2.0-november-2025.mdx          # Main release notes
├── deployment-guidelines-v5.2.mdx     # Deployment guide
└── update-environment-variables-5.2.mdx  # Env var updates

​
Scripts Available

Generates rich MDX matching v5.1.1/v5.2.0 format with thematic organization. Features:
  • Thematic tabs (Features & UX, Platform, Bug Fixes, Developer Experience)
  • Feature cards with nested tabs
  • Auto-categorization by theme (Accessibility, UI Designer, Workflow, etc.)
  • TODO markers for customization
  • Proper badges and icons
Usage: 
# Your standard query
node scripts/jira-to-rich-release-notes.js --jql "project IN (CORE, 'AI Integration', 'Rendering Product Team', 'MVP Team', Plugins, 'Platform Team', Documentation) AND fixVersion = 5.2 ORDER BY priority DESC"

# Simple version query
node scripts/jira-to-rich-release-notes.js 5.2.1

​
2. jira-release-notes.js

Generates simpler format with issue lists (good for quick reference).

​
3. jira-test-connection.js

Tests Jira API connectivity.

​
4. jira-list-versions.js

Lists available fix versions in your projects.

​
Template Structure

The generated template follows this structure: 
---
title: FlowX.AI X.X.X Release Notes
description: ...
mode: wide
---

**What's new?**

<Tabs>
  <Tab title="Features & UX">
    <!-- Major features -->
    
    ### **Feature Name**
    
    <Card title="Feature Name" icon="icon-name" iconType="duotone">
      <Tabs>
        <Tab title="Overview">
          <!-- Detailed description -->
        </Tab>
        <Tab title="Key Features">
          <CardGroup cols={2}>
            <Card title="Feature 1" icon="icon">
              Description
            </Card>
          </CardGroup>
        </Tab>
        <Tab title="Benefits">
          <!-- Business value -->
        </Tab>
      </Tabs>
      
      <!-- Badge -->
      <div className="flex justify-between items-center">
        <span className="...">Category Badge</span>
      </div>
    </Card>
    
    ---
    
  </Tab>
  
  <Tab title="Info">
    <!-- Deployment info, compatibility -->
  </Tab>
</Tabs>

​
Customization Tips

​
1. Add Rich Descriptions

Replace <!-- TODO: Add overview description --> with detailed content: 
<Tab title="Overview">
  FlowX.AI 5.2 introduces comprehensive accessibility features...
  
  <Frame>
  ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/feature.png)
  </Frame>
</Tab>

​
2. Add Key Features

Replace <CardGroup cols={2}> placeholder: 
<CardGroup cols={2}>
  <Card title="Feature Name" icon="icon-name">
    Detailed feature description with business value
  </Card>
  <Card title="Another Feature" icon="icon-name">
    Another feature description
  </Card>
</CardGroup>

​
3. Add Benefits or Use Cases

Add new tabs: 
<Tab title="Use Cases">
  <CardGroup cols={2}>
    <Card title="Government Applications" icon="landmark">
      Meet accessibility requirements for public sector
    </Card>
    <Card title="Healthcare" icon="hospital">
      Comply with healthcare accessibility regulations
    </Card>
  </CardGroup>
</Tab>

​
4. Add Steps or Accordions

<Tab title="Implementation">
  <Steps>
    <Step title="Configure">
      Step-by-step instructions
    </Step>
    <Step title="Test">
      Testing instructions
    </Step>
  </Steps>
</Tab>
Or use Accordions for collapsible content: 
<Accordion title="Technical Details">
  Detailed technical information that can be collapsed
</Accordion>

​
5. Adjust Tab Names

Change the top-level tab names to match your release themes: 
<Tabs>
  <Tab title="Accessibility & UX">
    <!-- Instead of generic "Features & UX" -->
  </Tab>
  <Tab title="Data & Security">
    <!-- Custom theme -->
  </Tab>
</Tabs>

​
Available MDX Components

Based on v5.1.1 and v5.2.0 examples:

​
Layout

  • <Tabs> / <Tab> - Tabbed content
  • <Card> - Feature cards with icons
  • <CardGroup cols={N}> - Grid of cards
  • <Accordion> - Collapsible sections
  • <Steps> / <Step> - Numbered steps

​
Content

  • <Info> - Info callouts (blue)
  • <Warning> - Warning callouts (yellow)
  • <Frame> - Images/videos
  • <CodeGroup> - Multi-language code examples

​
Icons

Common icons used:
  • universal-access - Accessibility
  • sparkles - Features
  • shield-halved - Security
  • database - Data
  • code - Development
  • palette - Design
  • gauge-high - Performance
  • robot - AI features
  • server - Platform

​
Badges

Badge color classes: 
bg-purple-100 dark:bg-purple-900 text-purple-800 dark:text-purple-300  # Major Enhancement
bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-300      # Stability
bg-blue-100 dark:bg-blue-900 text-blue-800 dark:text-blue-300          # Integration
bg-teal-100 dark:bg-teal-900 text-teal-800 dark:text-teal-300          # Developer Tools
bg-gray-100 dark:bg-gray-700 text-gray-800 dark:text-gray-300          # Platform Update

​
Example Workflow

# 1. List available versions
node scripts/jira-list-versions.js CORE

# 2. Generate rich template
node scripts/jira-to-rich-release-notes.js --jql "..." > release-notes-draft.mdx

# 3. Open in editor
cursor release-notes-draft.mdx

# 4. Customize:
#    - Fill in TODO sections
#    - Add images/videos
#    - Add detailed descriptions
#    - Adjust categorization if needed

# 5. Move to final location
mv release-notes-draft.mdx release-notes/v5.x/vX.X.X/vX.X.X.mdx

​
Tips for Great Release Notes

  1. Start with the template - The auto-generated structure is 90% there
  2. Add context - Explain WHY features matter, not just WHAT changed
  3. Use visuals - Screenshots and videos make features understandable
  4. Show examples - Code snippets help developers understand usage
  5. Organize by theme - Group related changes together
  6. Highlight impact - Use CardGroups to emphasize business value
  7. Link to docs - Add links to detailed documentation pages

​
Need Help?

  • Check existing release notes: release-notes/v5.x/v5.2.0-november-2025/
  • See component examples in v5.1.1 and v5.2.0
  • Test Jira connection: node scripts/jira-test-connection.js