Skip to content

REPORTING_GUIDE.md

Latest commit

 

History

History
565 lines (443 loc) · 13.2 KB

REPORTING_GUIDE.md

File metadata and controls

565 lines (443 loc) · 13.2 KB

Reporting Guide - Export Scrum Metrics

Overview

This guide covers exporting Trello CLI reports to various formats including HTML, PDF, Markdown, and JSON.

Report Types

1. Scrum Conformity Report

Generated from trello scrum-check <board_id>

2. Board Health Report

Generated from trello board-health <board_id>

3. Sprint Status Report

Generated from trello sprint-status <board_id>

4. Sprint Velocity Report

Generated from trello sprint-velocity <board_id>

Export Formats

JSON Export (Current Implementation)

All commands support JSON output for programmatic processing:

# Export to JSON
trello scrum-check <board_id> --json > report.json
trello board-health <board_id> --json > health.json

Markdown Export

# Export to Markdown
trello scrum-check <board_id> --markdown > SCRUM_REPORT.md
trello sprint-status <board_id> --markdown > SPRINT_STATUS.md

HTML Export

# Export to HTML
trello scrum-check <board_id> --html > report.html
trello board-health <board_id> --html > health.html

PDF Export

# Export to PDF (requires wkhtmltopdf)
trello scrum-check <board_id> --pdf report.pdf

Implementation Plan

Phase 1: Add JSON Export Flag

Update commands to support --json flag:

# trello_cli/commands/standardize.py

def cmd_scrum_check(board_id, output_format="text"):
    """
    Check board conformity with optional output format.

    Args:
        board_id: Board ID
        output_format: "text", "json", "markdown", "html"
    """
    # ... existing code ...

    report_data = {
        "board_id": board_id,
        "board_name": board.name,
        "score": score,
        "status": status,
        "issues": issues,
        "checks": {
            "required_lists": required_lists_result,
            "wip_limits": wip_limits_result,
            "sprint_size": sprint_size_result,
            "testing_queue": testing_queue_result,
            "backlog_health": backlog_health_result,
        },
        "recommendations": recommendations,
        "timestamp": datetime.now().isoformat()
    }

    if output_format == "json":
        print(json.dumps(report_data, indent=2))
        return

    # ... existing text output ...

Phase 2: Markdown Templates

# trello_cli/utils/reporters.py

def generate_markdown_report(report_data):
    """Generate Markdown report from data"""
    md = f"""# Scrum Conformity Report

**Board**: {report_data['board_name']}
**Date**: {report_data['timestamp']}
**Score**: {report_data['score']}/100 - {report_data['status']}

## Summary

- Board ID: `{report_data['board_id']}`
- Issues Found: {len(report_data['issues'])}

## Checks Performed

### ✅ Required Lists
{_format_check_results(report_data['checks']['required_lists'])}

### ⚙️ WIP Limits
{_format_check_results(report_data['checks']['wip_limits'])}

### 📝 Sprint Size
{_format_check_results(report_data['checks']['sprint_size'])}

### 🧪 Testing Queue
{_format_check_results(report_data['checks']['testing_queue'])}

### 📋 Backlog Health
{_format_check_results(report_data['checks']['backlog_health'])}

## Issues

{_format_issues(report_data['issues'])}

## Recommendations

{_format_recommendations(report_data['recommendations'])}

---
*Generated by Trello CLI v2.1*
"""
    return md

Phase 3: HTML Templates

# trello_cli/utils/reporters.py

HTML_TEMPLATE = """
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Scrum Conformity Report - {board_name}</title>
    <style>
        body {{
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;
            max-width: 1200px;
            margin: 0 auto;
            padding: 20px;
            background: #f5f5f5;
        }}
        .header {{
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            color: white;
            padding: 30px;
            border-radius: 10px;
            margin-bottom: 30px;
        }}
        .score {{
            font-size: 48px;
            font-weight: bold;
        }}
        .status {{
            font-size: 24px;
            margin-top: 10px;
        }}
        .section {{
            background: white;
            padding: 20px;
            margin-bottom: 20px;
            border-radius: 8px;
            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
        }}
        .check {{
            display: flex;
            align-items: center;
            padding: 10px 0;
            border-bottom: 1px solid #eee;
        }}
        .check-icon {{
            font-size: 24px;
            margin-right: 15px;
        }}
        .issue {{
            background: #fff3cd;
            border-left: 4px solid #ffc107;
            padding: 15px;
            margin: 10px 0;
        }}
        .recommendation {{
            background: #d1ecf1;
            border-left: 4px solid #17a2b8;
            padding: 15px;
            margin: 10px 0;
        }}
    </style>
</head>
<body>
    <div class="header">
        <h1>{board_name}</h1>
        <div class="score">{score}/100</div>
        <div class="status">{status}</div>
        <p>Report generated: {timestamp}</p>
    </div>

    <div class="section">
        <h2>📋 Required Lists Check</h2>
        {required_lists_html}
    </div>

    <div class="section">
        <h2>⚙️ WIP Limits Check</h2>
        {wip_limits_html}
    </div>

    <div class="section">
        <h2>📝 Sprint Size Check</h2>
        {sprint_size_html}
    </div>

    <div class="section">
        <h2>🧪 Testing Queue Check</h2>
        {testing_queue_html}
    </div>

    <div class="section">
        <h2>📋 Backlog Health</h2>
        {backlog_health_html}
    </div>

    <div class="section">
        <h2>⚠️ Issues Found</h2>
        {issues_html}
    </div>

    <div class="section">
        <h2>💡 Recommendations</h2>
        {recommendations_html}
    </div>

    <footer style="text-align: center; margin-top: 40px; color: #666;">
        <p>Generated by Trello CLI v2.1</p>
    </footer>
</body>
</html>
"""

def generate_html_report(report_data):
    """Generate HTML report from data"""
    return HTML_TEMPLATE.format(
        board_name=report_data['board_name'],
        score=report_data['score'],
        status=report_data['status'],
        timestamp=report_data['timestamp'],
        required_lists_html=_format_checks_html(report_data['checks']['required_lists']),
        wip_limits_html=_format_checks_html(report_data['checks']['wip_limits']),
        sprint_size_html=_format_checks_html(report_data['checks']['sprint_size']),
        testing_queue_html=_format_checks_html(report_data['checks']['testing_queue']),
        backlog_health_html=_format_checks_html(report_data['checks']['backlog_health']),
        issues_html=_format_issues_html(report_data['issues']),
        recommendations_html=_format_recommendations_html(report_data['recommendations'])
    )

Phase 4: PDF Export

Using weasyprint or pdfkit:

# trello_cli/utils/reporters.py

def generate_pdf_report(report_data, output_file):
    """Generate PDF report from HTML"""
    try:
        from weasyprint import HTML
    except ImportError:
        print("❌ PDF export requires weasyprint: pip install weasyprint")
        return False

    html_content = generate_html_report(report_data)

    HTML(string=html_content).write_pdf(output_file)
    print(f"✅ PDF report saved to: {output_file}")
    return True

Usage Examples

Export Multiple Boards to HTML

#!/bin/bash
# export_all_boards.sh

OUTPUT_DIR="reports/$(date +%Y%m%d)"
mkdir -p "$OUTPUT_DIR"

# Get all board IDs
BOARDS=$(trello boards | awk '{print $1}')

for board_id in $BOARDS; do
    echo "Generating report for $board_id..."

    trello scrum-check "$board_id" --html > "$OUTPUT_DIR/${board_id}_scrum.html"
    trello board-health "$board_id" --html > "$OUTPUT_DIR/${board_id}_health.html"
    trello sprint-status "$board_id" --html > "$OUTPUT_DIR/${board_id}_sprint.html"
done

echo "✅ Reports saved to $OUTPUT_DIR"

Automated Daily Reports

#!/bin/bash
# daily_report.sh

BOARD_ID="68fcf05e481843db13204397"
DATE=$(date +%Y-%m-%d)
REPORT_FILE="daily_reports/${DATE}_report.html"

trello scrum-check "$BOARD_ID" --html > "$REPORT_FILE"

# Email report (optional)
mail -s "Daily Scrum Report - $DATE" team@example.com < "$REPORT_FILE"

Dashboard Generation

#!/usr/bin/env python3
"""
generate_dashboard.py - Create HTML dashboard for all boards
"""

import subprocess
import json
from datetime import datetime

def get_all_boards():
    """Get all board IDs"""
    result = subprocess.run(['trello', 'boards'], capture_output=True, text=True)
    # Parse output to get board IDs
    return board_ids

def generate_board_report(board_id):
    """Generate report for a board"""
    result = subprocess.run(
        ['trello', 'scrum-check', board_id, '--json'],
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

def create_dashboard():
    """Create HTML dashboard"""
    boards = get_all_boards()
    reports = [generate_board_report(bid) for bid in boards]

    # Generate dashboard HTML
    dashboard_html = f"""
    <!DOCTYPE html>
    <html>
    <head>
        <title>Trello Dashboard - {datetime.now().strftime('%Y-%m-%d')}</title>
        <style>
            /* Dashboard styles */
        </style>
    </head>
    <body>
        <h1>Trello Boards Dashboard</h1>
        <div class="boards-grid">
            {generate_board_cards(reports)}
        </div>
    </body>
    </html>
    """

    with open('dashboard.html', 'w') as f:
        f.write(dashboard_html)

    print("✅ Dashboard generated: dashboard.html")

if __name__ == '__main__':
    create_dashboard()

Scheduled Reports

Cron Job for Weekly Reports

# Add to crontab: crontab -e

# Run every Monday at 9 AM
0 9 * * 1 /path/to/trello-cli-python/scripts/weekly_report.sh

# Run daily at 8 AM
0 8 * * * /path/to/trello-cli-python/scripts/daily_report.sh

GitHub Actions for CI Reports

# .github/workflows/weekly-report.yml
name: Weekly Scrum Report

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM
  workflow_dispatch:  # Manual trigger

jobs:
  generate-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install Trello CLI
        run: |
          pip install -r requirements.txt
          export PATH="$PWD:$PATH"

      - name: Generate Reports
        env:
          TRELLO_API_KEY: ${{ secrets.TRELLO_API_KEY }}
          TRELLO_TOKEN: ${{ secrets.TRELLO_TOKEN }}
        run: |
          mkdir -p reports
          trello scrum-check ${{ secrets.BOARD_ID }} --html > reports/scrum_report.html

      - name: Upload Reports
        uses: actions/upload-artifact@v3
        with:
          name: weekly-reports
          path: reports/

Report Templates

Custom Templates Directory

trello-cli-python/
├── templates/
│   ├── scrum_report.html
│   ├── health_report.html
│   ├── sprint_status.html
│   └── dashboard.html

Template Variables

Available variables for templates:

{
    'board_id': str,
    'board_name': str,
    'timestamp': str (ISO format),
    'score': int (0-100),
    'status': str,
    'issues': List[str],
    'checks': {
        'required_lists': Dict,
        'wip_limits': Dict,
        'sprint_size': Dict,
        'testing_queue': Dict,
        'backlog_health': Dict
    },
    'recommendations': List[str],
    'metadata': {
        'generated_by': 'Trello CLI v2.1',
        'cli_version': '2.1.0'
    }
}

Dependencies

For HTML/PDF Export

pip install weasyprint  # For PDF generation
# or
pip install pdfkit      # Alternative PDF library

For Email Reports

pip install sendgrid    # For SendGrid email
# or use built-in smtplib

Best Practices

  1. Store Reports in Git: Keep historical reports for trend analysis
  2. Automate Generation: Use cron jobs or CI/CD
  3. Version Control: Include report generation date and CLI version
  4. Secure Credentials: Use environment variables for API keys
  5. Archive Old Reports: Keep last 30 days, archive rest

Future Enhancements

  • Excel export for spreadsheet analysis
  • Charts and graphs in HTML reports
  • Email integration for automated delivery
  • Slack/Teams notifications
  • Historical trend analysis
  • Multi-board comparison reports
  • Custom report templates
  • Interactive web dashboard

Troubleshooting

Issue: PDF Generation Fails

# Install system dependencies for weasyprint
# macOS:
brew install python3 cairo pango gdk-pixbuf libffi

# Ubuntu/Debian:
sudo apt-get install python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0

Issue: HTML Not Rendering Properly

  • Check template syntax
  • Validate HTML with W3C validator
  • Test CSS separately

Issue: Large Files

  • Compress images
  • Minify CSS/JS
  • Use external CDN for libraries

Resources