v2.5.0

v2.5.0

Released: 2026-05-21

Highlights

Patch release adding an overall summary narrative to the curated highlights output when --llm-summary is enabled. Closes a UX gap that surfaced on the very first real run of v2.4.0 in QuantEcon/meta#307: the placeholder text at the top of highlights.md advertised "or use --llm-summary to draft one" but the feature only generated per-theme summaries, not an overall one. The placeholder was writing a promise the feature didn't keep.

This release makes the placeholder honest.

Behaviour change

When --llm-summary is set:

1. Per-theme narratives generate as before (one Claude call per active theme).
2. NEW: one synthesis call takes those narratives + auxiliary counts (releases / translation-sync / maintenance) + contributor list and writes 2-3 sentences capturing the arc of the period — the headline story and what areas saw the most substantial work.
3. The result replaces the placeholder at the top of highlights.md, rendered in italics matching the per-theme narrative style.

When --llm-summary is not set: no behaviour change. The placeholder text stays exactly as before.

Failure handling matches the per-theme path: network/decode/shape failures log a warning to stderr and the script falls back to the placeholder. The build never fails over a missing narrative.

Sample output

Against the 2026-04-21..05-20 QuantEcon window:

The dominant thread of the period was a coordinated modernisation of QuantEcon's lecture content and supporting libraries, centred on replacing deprecated np.random calls with the Generator API across seven lectures and extending that guidance into the quantecon library itself alongside new NormalFormGame constructor support. New lectures on Kihlstrom's paper, the Ross Recovery Theorem, and probability theory added meaningful content depth at the same time. Infrastructure saw sustained attention too, with Dependabot automation, security remediation, a refreshed quantecon.org design, and a string of tooling releases delivering book-style numbering, CommonMark IPYNB export, and macOS build fixes.

Real synthesis. Identifies the headline story ("lecture content and library modernisation"), names specific projects (NormalFormGame, Kihlstrom, Ross Recovery Theorem, QuantEcon.org), and frames the period as deliberate modernization rather than incremental noise.

Cost

	v2.4.0	v2.5.0
Anthropic API calls per run	N per-theme	N per-theme + 1 synthesis
Per-run cost (Sonnet default)	~6¢	~7¢
Wall time	~10s	~17s
Heuristic-only path (no flag)	unchanged	unchanged

Internal refactor

Two small extractions in tools/highlights.py to clean up the bucketing in build_highlights():

• _claude_message() — shared urllib + JSON plumbing for both the per-theme and overall-summary LLM calls.
• _unique_contributors() — de-duplication + bot-filter + sort, used both by the thank-you-line renderer and as a signal into the overall-summary prompt. render_contributors() is now a pure formatter taking a pre-deduped handle list, so build_highlights() computes the list once and passes it to both consumers without re-deduping.

Migration

No breaking changes. Workflows pinning @v2 automatically pick up this release. To opt into the overall-summary behaviour, you just need --llm-summary (or llm-summary: 'true' in action mode) — which you already have if you were using LLM narratives in v2.4.0.

See docs/highlights.md for the updated feature reference describing the two-stage LLM behaviour.

v2.4.0

v2.4.0

Released: 2026-05-21

Highlights

This release adds a curated highlights view and the structured data export underneath it — the automated counterpart to the hand-written highlights comments at QuantEcon/meta#259 and #291.

Three layers ship together:

1. report-data.json is emitted on every run alongside the markdown report. Stable schema, no flag required. Source-of-truth for any downstream tooling.
2. tools/highlights.py consumes it to produce highlights.md — PRs grouped into themes (Lectures / Libraries / Tooling / Courses / Other), bot/dependency noise rolled up into a collapsed "Maintenance & Dependencies" block, translation-sync PRs in their own collapsed "🌐 Translation Sync" section, releases summary table at the top, contributor thank-you line auto-populated. Pure Python stdlib, runs in under a second.
3. --llm-summary (opt-in) draws a one-sentence narrative per theme via Claude. Default model is claude-sonnet-4-6 (selected after a side-by-side against Haiku on real QuantEcon data — Sonnet caught noticeably more specific PRs / projects / classes). Failures degrade gracefully.

The release also folds in two earlier infrastructure changes from the same review cycle: per-endpoint pagination (fixes silent truncation past 100 items per repo) and the offline fixture-based test suite (replaces the prior toy test-basic.sh mock).

Added

• Curated highlights (tools/highlights.py): theme-grouped, noise-suppressed view of merged PRs; see docs/highlights.md.
• --highlights CLI flag and highlights action input, plus --highlights-file= / highlights-file: for custom output filenames.
• --llm-summary CLI flag and llm-summary action input that draws per-theme narratives via Claude; requires ANTHROPIC_API_KEY in the environment. Default model claude-sonnet-4-6, overridable with --llm-model / llm-model.
• highlights action output exposing the rendered content for downstream workflow steps (e.g., posting as a PR/issue comment).
• Structured data export: every run emits report-data.json alongside the markdown report. Stable schema documented in docs/report-data-schema.md. Filename derives from the markdown output (report.md → report-data.json, weekly-report.md → weekly-report-data.json).
• Translation Sync collapsed section in highlights.md — PRs carrying the action-translation label render in their own dedicated section instead of dominating Lectures.
• Fixture-based test suite under tests/: mock-curl harness replays recorded GitHub API responses against generate-report.sh and diffs against golden files. Eight scenarios (happy path, summary template, empty range, pagination, external repos, partial failure, highlights/mixed, highlights/noise-only). Runs offline in CI in about a second; entry point tests/run-fixtures.sh. See tests/README.md.

Fixed

• Per-endpoint pagination: per-repository API calls (issues, pulls, commits, releases) now paginate through all pages. Previously only the first 100 items were fetched, silently truncating data for active repos over multi-week windows.
• .user.login null safety: PRs authored by a since-deleted GitHub account would surface @null in the comment-template output. Both jq projections now coalesce to empty string; the highlights renderer also skips the trailing (@author) mention when author is empty.

Changed

• Consolidated API calls: per-repo call count reduced from 7 to 5. A single issues?state=all&since=... call now covers both "opened in range" and "closed in range"; a single pulls?state=all&sort=updated call covers both "opened" and "merged".
• New api_call_paginated helper: generic pagination wrapper around api_call with an optional early-exit when items become older than the report window. Used for org-repo discovery, all per-repo metric collection, and external-repo processing.
• Documentation pass: new docs/highlights.md and docs/report-data-schema.md; docs/testing.md rewritten to lead with the fixture suite; docs/comment-summary-template.md clarified as the raw-dump-for-hand-curation counterpart to --highlights; docs/README.md reorganised as an index; README.md workflow example expanded to show all four emitted artifacts.

Removed

• output-format action input: the markdown/json selector was advertised but never implemented — only markdown was ever produced. Removed from action.yml, the README, and the CLI help text. Workflows that explicitly pass output-format get a GitHub Actions warning about an unrecognised input but continue to work (markdown output is unchanged).
• tests/test-basic.sh: an inline-mock script that never exercised the real generate-report.sh. Replaced by the fixture suite.

Verification

Verified against the live QuantEcon org on multiple windows:

• 2026-04-01..04-15 (used for the v2.3.0 baseline-equivalence test on PR #4): pagination + API-consolidation refactor produces byte-identical report.md and comment-template.md output (modulo the auto-generated timestamp footer).
• 2026-04-21..05-20 (a real 30-day window): --highlights produces a clean themed view with 8 substantive Lecture PRs (down from 25 once translation-sync moved to its own section), 5 Library PRs, 5 Tooling PRs, 18 mystmd PRs in "Other", 18 translation-sync PRs collapsed, 27 dependency rollups, and 5 non-bot contributors. --llm-summary adds specific, accurate per-theme narratives — example, Libraries: "Extended NormalFormGame and Player to support tuple-based constructors and payoff display, fixed field docstring syntax, and added NumPy random Generator API guidance."

Migration

No breaking changes. Existing workflows pinning @v2 automatically pick up everything in this release. To opt into the new features:

- name: Generate weekly report
  uses: QuantEcon/action-weekly-report@v2
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    organization: 'QuantEcon'
    highlights: 'true'         # new: produces highlights.md
    llm-summary: 'true'        # new (optional): adds LLM-drafted theme narratives
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}  # only needed when llm-summary: 'true'

See docs/highlights.md for the full feature reference and docs/report-data-schema.md for the structured data format.

v2.3.0

Highlights

This release introduces the comment summary template — an auto-generated markdown template that collects all merged PR data and release activity from the report period, giving maintainers a starting point for writing activity summary comments.

Also included: release tracking in both the main report table and the summary template, a --debug flag to gate verbose output, and numerous bug fixes.

Added

• Comment summary template with --summary-template flag and comment-template action output
• Release tracking in summary template (releases table sorted by date)
• Releases column in main activity report table
• --debug flag to gate all debug output (silent by default)

Fixed

• set -e safety: Restructured API call assignments so failures don't abort the script
• Date formatting: Non-zero-padded days in releases table (Feb 5 not Feb 05)
• Corrupted docs: Rewrote docs/testing.md and tests/README.md
• CLI error message: GITHUB_OUTPUT warning now only shown in debug mode
• Hyperlinks docs: Fixed "metrics > 1" to match actual "> 0" behavior

Changed

• CONTRIBUTING.md: Updated to accurate shell-project instructions
• Debug output: All debug messages gated behind --debug flag
• Removed no-op shift statements in argument parsing
• Softened docs wording and documented 100-item API page limit

Full Changelog: v2.2.0...v2.3.0

v2.2.0

🌐 External Repository Tracking

Track activity across repositories outside your primary organization! This release adds the ability to monitor repositories from other organizations alongside your own.

✨ What's New

Track External Repositories:

• New --track-external-repos CLI flag and track-external-repos action input
• Format: comma-separated org/repo pairs
• Example: executablebooks/sphinx-proof,executablebooks/sphinx-exercise
• Separate "External Repositories" section in report
• Independent totals for external repos
• Full org/repo format displayed for clarity

🎯 Use Cases

• Monitor dependencies you contribute to
• Track upstream projects you collaborate with
• Include forked repositories from other organizations
• Cross-organization project tracking

📊 Report Format

External repositories appear in a dedicated section below your main organization table:

## External Repositories

| Repository | Current Issues | Opened Issues | Closed Issues | Opened PRs | Merged PRs | Commits |
|------------|----------------|---------------|---------------|------------|------------|---------|
| executablebooks/sphinx-proof | 27 | 0 | 1 | 4 | 8 | 14 |
| executablebooks/sphinx-exercise | 18 | 0 | 1 | 4 | 4 | 9 |
|**Total**|**45**|**0**|**2**|**8**|**12**|**23**|

💻 Usage

CLI:

./generate-report.sh --token=ghp_xxx \
  --track-external-repos=executablebooks/sphinx-proof,executablebooks/sphinx-exercise

GitHub Actions:

- uses: QuantEcon/action-weekly-report@v2.2.0
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    track-external-repos: 'executablebooks/sphinx-proof,executablebooks/sphinx-exercise'

✅ Features

• ✅ Works with public repositories using same token
• ✅ Validates org/repo format with clear error messages
• ✅ Only displays section when external repos have activity
• ✅ All metrics include clickable hyperlinks (like main section)
• ✅ Comprehensive validation tests included

📝 Full Changelog

See CHANGELOG.md for complete details.

Upgrade: Use @v2 tag to automatically get this release, or pin to @v2.2.0 for version stability.

v2.1.2

🔧 v2.1.2 - Patch Release (Output Mapping Fix)

Critical fix for composite action outputs + helpful pattern validation warnings.

🐛 Critical Fix

Composite Action Outputs Now Work

• Fixed empty report-content and report-summary outputs
• Added proper step ID and output value mappings
• Resolves CI test failures and workflow integration issues

Before: Outputs were empty (${{ steps.test-report.outputs.report-content }} = "")
After: Outputs properly contain report content and summary

✨ New Feature

Pattern Match Validation

Exclude patterns (2 total):
  - Pattern: 'lecture-\.notebooks'
  - Pattern: 'test-.*'
  ✗ Excluding: test-translation-sync (matched 'test-.*')

  ⚠️  Warning: Pattern 'lecture-\.notebooks' didn't match any repositories
Repositories after filtering: 24 (excluded: 1)

Helps catch common mistakes:

• Missing .* for wildcards → lecture-\.notebooks should be lecture-.*\.notebooks
• Typos in patterns
• Wrong escaping

🧪 CI Improvements

• Verifies weekly-report.md file exists
• Shows directory listing on failure
• Reports file size for debugging

📋 Migration

No changes required - This is a bug fix release.

Workflows will now properly receive outputs:

- name: Generate report
  id: report
  uses: QuantEcon/action-weekly-report@v2
  
- name: Use outputs
  run: |
    echo "${{ steps.report.outputs.report-summary }}"  # ✅ Now works!

🔗 Links

• Full Changelog
• v2.1.1 - Backward compatibility fix
• v2.1.0 - Regex support

v2.1.1 - Backward Compatibility Fix

🔧 v2.1.1 - Patch Release (Backward Compatibility Fix)

Critical patch release fixing output filename for GitHub Actions workflows.

🐛 Bug Fix

Restored weekly-report.md for GitHub Actions

• Previous v2.1.0 changed default to report.md, breaking existing workflows
• Now auto-detects execution context:
  • ✅ GitHub Actions: weekly-report.md (backward compatible)
  • ✅ CLI mode: report.md (cleaner for local dev)
• Both modes support custom --output flag

✨ Improvements

Enhanced Debug Output

Exclude patterns (2 total):
  - Pattern: 'lecture-.*\.notebooks'
  - Pattern: 'test-.*'
  ✗ Excluding: lecture-python.notebooks (matched 'lecture-.*\.notebooks')
  ✗ Excluding: test-translation-sync (matched 'test-.*')
Repositories after filtering: 24

• Shows each pattern being tested
• Displays which repos matched which patterns
• Visual indicators for excluded repos
• Repository count before/after filtering

📋 Migration

No changes required - This release fixes the regression introduced in v2.1.0.

Existing workflows will work correctly:

- uses: QuantEcon/action-weekly-report@v2
  # Outputs to weekly-report.md automatically
  
- uses: peter-evans/create-issue-from-file@v4
  with:
    content-filepath: weekly-report.md  # ✅ Works now

�� Links

• Full Changelog
• v2.1.0 Release (regex support)
• v2.0.0 Release (major rewrite)

v2.1.0 - Regex Support for Repository Exclusion

🎉 v2.1.0 - Regex Support for Repository Exclusion

Minor feature release adding regex pattern support to the exclude-repos option!

✨ What's New

Regex Pattern Matching - Exclude groups of repositories with a single pattern:

# Before: List each repo individually
exclude-repos: 'lecture-python.notebooks,lecture-julia.notebooks,lecture-datascience.notebooks'

# After: Use regex pattern
exclude-repos: 'lecture-.*\.notebooks'

🚀 Usage Examples

CLI Mode:

# Exclude all .notebooks repositories
./generate-report.sh --token=ghp_xxx --exclude="lecture-.*\.notebooks"

# Multiple patterns
./generate-report.sh --token=ghp_xxx --exclude="lecture-.*\.notebooks,.*-archive"

GitHub Actions:

- uses: QuantEcon/action-weekly-report@v2.1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    exclude-repos: 'lecture-.*\.notebooks,.*-archive'

📋 Common Patterns

Pattern	Matches
lecture-.*\.notebooks	All repos: lecture-*.notebooks
.*-archive	All repos ending with "-archive"
test-.*	All repos starting with "test-"
.*\.(notebooks|archive)	Repos ending with .notebooks or .archive

✅ Key Features

• ✅ Flexible matching - Use standard regex syntax
• ✅ Backward compatible - Exact names still work
• ✅ Mixed usage - Combine exact names and patterns
• ✅ Debug output - Shows which pattern matched each repo

🔄 Migration

100% backward compatible - No changes required for existing workflows.

Optional upgrade to use regex patterns for more concise configuration.

📚 Documentation

• Release Notes - Full details
• Technical Details - Implementation
• CHANGELOG - Version history

Perfect for organizations with systematic naming conventions! 🚀

v2.0.0

🎉 Major Release - Complete Rewrite

This release transforms the action from a basic search-based tool into a comprehensive, accurate activity tracker with CLI support, critical bug fixes, and extensive validation.

✨ Key Features

CLI Support

Full command-line interface for standalone execution:

# Generate report for last 7 days
./generate-report.sh --token=ghp_xxx --org=QuantEcon

# Custom date range
./generate-report.sh --token=ghp_xxx --start=2025-10-01 --end=2025-10-31

# Show help
./generate-report.sh --help

5 Critical Bugs Fixed

1. Date Range Upper Bound - Was counting activity beyond end date (inflated metrics)
2. Pagination Missing - Only checked first 100 repos (QuantEcon has 209)
3. Dangerous Fallback - Wasted 500 API calls on quiet days
4. Opened Issues State - Undercounted issues created and closed in same period
5. Token Validation - No upfront validation, confusing errors

Enhanced Tracking

• Opened PRs column - Track PR creation, not just merges
• Commits column - Direct commit count per repository
• Post-processing filter - Excludes repos with zero activity
• Token validation - Validates token on startup with clear errors

Cross-Platform Support

• ✅ macOS (BSD tools)
• ✅ Linux (GNU tools)
• ✅ GitHub Actions (both platforms)

📊 Validation

All metrics 100% accurate - Cross-validated against GitHub API/UI:

• action-translation-sync: 57 commits (was completely missing)
• test-translation-sync: 21 opened PRs, 20 merged
• lecture-python.myst: 2 opened issues (was showing 1)
• Oct 5 (Sunday): 0 activity (was showing 7 merged PRs)

🔄 Migration

100% Backward Compatible - Existing workflows work without changes:

- uses: QuantEcon/action-weekly-report@v2
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

📚 Documentation

Complete documentation in docs/ folder:

• Release Notes - Full details
• Technical Details - Implementation
• Testing Guide - How to test
• Validation - Real-world examples

🚀 Getting Started

As GitHub Action:

- name: Generate activity report
  uses: QuantEcon/action-weekly-report@v2
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

As CLI Tool:

./generate-report.sh --token=ghp_xxx --org=YourOrg

See CHANGELOG.md for complete details.