QuantEcon GitHub Actions - End of Year Status Report 2025

# QuantEcon GitHub Actions - End of Year Status Report 2025

**Report Date:** December 30, 2025  
**Reporting Period:** October - December 2025

---

## Executive Summary

Over the past few months, QuantEcon has developed five custom GitHub Actions to automate and improve the quality of our lecture series maintenance. These actions leverage AI (Claude) to provide intelligent automation for translation, style checking, link validation, warning detection, and activity reporting.

| Action | Current Version | Status | Development Stage |
|--------|-----------------|--------|-------------------|
| [action-translation](https://github.com/QuantEcon/action-translation) | v0.7.0 | ✅ Testing & Development | Active Development |
| [action-style-guide](https://github.com/QuantEcon/action-style-guide) | v0.5.1 | ✅ Testing & Development | Active Development |
| [action-weekly-report](https://github.com/QuantEcon/action-weekly-report) | v2.2.0 | ✅ Deployed | Stable |
| [action-check-warnings](https://github.com/QuantEcon/action-check-warnings) | v1.0.0 | ✅ Final Testing | Stable |
| [action-link-checker](https://github.com/QuantEcon/action-link-checker) | v1.0.0 | ✅ Final Testing | Stable |
| [workflow-backups](https://github.com/QuantEcon/workflow-backups) | v0.3.0 | ✅ Final Testing | Stable |
---

## Deployment Matrix: Python Lecture Series

The following table shows which QuantEcon Actions are currently deployed or being tested across our Python lecture repositories:

| Repository | Translation | Style Guide | Link Checker | Check Warnings | Weekly Report | Backups |
|------------|:-----------:|:-----------:|:------------:|:--------------:|:-------------:|:-------:|
| [lecture-python-programming.myst](https://github.com/QuantEcon/lecture-python-programming.myst) | - | - | ✅ Testing | - | - | ✅ 29 Dec 2025 (1) |
| [lecture-python-advanced.myst](https://github.com/QuantEcon/lecture-python-advanced.myst) | - | ✅ Testing | - | - | - | ✅ 29 Dec 2025 (6) |
| [lecture-python-intro](https://github.com/QuantEcon/lecture-python-intro) | - | - | - | - | - | ✅ 29 Dec 2025 (6) |
| [lecture-jax](https://github.com/QuantEcon/lecture-jax) | - | - | - | - | - | ✅ 29 Dec 2025 (1) |
| [lecture-python.myst](https://github.com/QuantEcon/lecture-python.myst) | - | - | - | - | - | ✅ 29 Dec 2025 (6) |
| [continuous_time_mcs](https://github.com/QuantEcon/continuous_time_mcs) | - | - | - | - | - | ✅ 29 Dec 2025 (8) |

---

## Individual Action Details

### 1. Translation Action (`action-translation`)

**Purpose:** Automatically synchronizes and reviews translations across lecture repositories using Claude AI.

**Key Features:**
- 🌍 Two modes: **Sync Mode** (translate changes) and **Review Mode** (quality assessment)
- 🗺️ Heading-Map System for robust cross-language section matching
- 🔄 Intelligent diff translation (only translates changed sections)
- 📚 Built-in glossaries: Chinese (357 terms), Persian/Farsi (357 terms)
- ✅ 183 unit tests passing, 24 GitHub integration scenarios

**Version History:**
- v0.7.0 (Dec 2025): Added Review Mode, renamed from `action-translation-sync`
- Includes companion tools: bulk-translator, alignment tool, onboarding tool

**Current Status:** Testing & Development  
**Next Steps:** Deploy to translation target repositories (lecture-python.zh-cn) and working on initial sync feature.

---

### 2. Style Guide Checker (`action-style-guide`)

**Purpose:** AI-powered style guide compliance checker for QuantEcon lecture materials.

**Key Features:**
- 🤖 Uses Claude Sonnet 4.5 for intelligent style analysis
- 🏷️ 8 category-based reviews: writing, math, code, jax, figures, references, links, admonitions
- 📝 50+ style rules with focused prompts
- 🔄 Automated fix application with sequential category processing
- 🏷️ PR management with detailed explanations

**Rule Types:**
- `rule` (Actionable): Auto-applied fixes
- `style` (Advisory): Suggestions requiring human judgment
- `migrate` (Code Modernization): Legacy pattern updates (JAX/code)

**Version History:**
- v0.5.1 (Dec 2025): Critical hotfix for NameError
- v0.5.0 (Dec 2025): Production testing infrastructure, PR labels, @qe-style-checker syntax
- v0.4.0 (Dec 2025): Type terminology, CLI tool integration

**Current Deployments:**
- `lecture-python-advanced.myst` - Active testing ([Issue #261](https://github.com/QuantEcon/lecture-python-advanced.myst/issues/261))
- `test-action-style-guide` - Dedicated test repository

**Next Steps:** Continue testing program to ensure we have actionable, concise and useful suggestions. 

---

### 3. Weekly Report Action (`action-weekly-report`)

**Purpose:** Generates comprehensive activity reports across GitHub organizations.

**Key Features:**
- 📊 Comprehensive analytics: Issues, PRs, commits, activity summaries
- 🔗 Clickable metrics linking directly to GitHub search results
- 🌐 External repository tracking (e.g., executablebooks/sphinx-proof)
- ⚡ Handles organizations with 100+ repositories via pagination
- 💻 CLI support for local development

**Version History:**
- v2.2.0 (Oct 2025): External repository tracking
- v2.0.0: Complete rewrite with CLI, pagination, critical improvements

**Current Deployments:**
- `QuantEcon/meta` - Weekly automated reports for entire QuantEcon organization
  - Tracks external repos: `executablebooks/sphinx-exercise`, `executablebooks/sphinx-proof`
  - Runs every Saturday at 9:00 AM UTC

**Status:** Production - Stable

---

### 4. Check Warnings Action (`action-check-warnings`)

**Purpose:** Scans HTML documentation for Python warnings within code cell outputs.

**Key Features:**
- 🔍 Smart detection: Only scans warnings within `cell_output` class elements
- 📋 Supports all Python warning types by default
- 🎛️ Configurable: Exclude specific warning types
- 📊 Multiple outputs: GitHub issues, artifacts, PR comments
- 🎯 Perfect for Jupyter Book documentation builds

**Version:** v1.0.0

**Current Status:** Ready for deployment  
**Recommended for:** All lecture repositories to catch warnings in documentation builds

---

### 5. Link Checker Action (`action-link-checker`)

**Purpose:** AI-powered link validation in HTML files with intelligent suggestions.

**Key Features:**
- 🤖 AI-powered suggestions for broken/redirected links
- 🔍 Bot-blocking awareness to reduce false positives
- ⚡ Two modes: Full project scan or PR-changed files only
- 📊 Rich reporting: GitHub issues, artifacts, JSON output
- 🔧 Configurable: Custom timeouts, status codes, behaviors

**AI Suggestion Types:**
- HTTPS upgrades
- GitHub branch updates (master → main)
- Documentation migration suggestions
- Version updates for deprecated docs

**Version:** v1.0.0

**Current Deployments:**
- `lecture-python-programming.myst` - Weekly scheduled checks (Monday 9am AEDT)

**Status:** Testing - Stable

---

### 6. Repository Backup Workflow (`workflow-backups`)

**Purpose:** Centralized workflow for backing up QuantEcon repositories to AWS S3 for disaster recovery and compliance.

**Key Features:**
- 📦 Pattern-based selection: Use regex patterns to select repositories
- 🔄 Mirror backups: Complete repository backups including all branches, tags, and history
- ☁️ AWS S3 storage with OIDC authentication (no static credentials)
- ⏭️ Skip existing: Automatic duplicate detection
- 📊 Backup reporting with monthly review reminders
- 📝 GitHub issues metadata backup (optional)

**Backup Storage Structure:**
```
s3://bucket-name/
├── repo-name/
│   ├── repo-name-20251127.tar.gz
│   ├── repo-name-issues-20251127.json
│   └── ...
└── another-repo/
    └── another-repo-20251127.tar.gz
```

**Version History:**
- v0.3.0 (Dec 2025): GitHub issues metadata backup feature
- v0.2.0: Exclusion features and code quality improvements
- v0.1.0: Initial release with S3 backup functionality

**Current Configuration (config.yml - Active Testing):**

| Category | Repositories | Notes |
|----------|--------------|-------|
| **Explicit Repos** | `continuous_time_mcs`, `QuantEcon.manual`, `sphinx-tojupyter`, `lecture-wasm`, `lecture-python-advanced.myst`, `lecture-python-intro`, `lecture-python.myst`, `lecture-jax`, `lecture-python-programming.myst` | Test repos including largest lecture sites |
| **Pattern: `action-.*`** | ~5 repos | All GitHub Actions |
| **Pattern: `QuantEcon.*`** | ~11 repos | Core libraries (QuantEcon.py, QuantEcon.jl, etc.) |

**Available Configuration Profiles:**

| Profile | File | Purpose |
|---------|------|---------|
| Testing | `config.yml` | Current active config - selected test repos |
| Core | `config.quantecon-core.yml` | Essential assets only (libraries, active lectures, infrastructure) |
| Full | `config.quantecon-all.yml` | Complete org backup with all patterns |

**Exclusions (deprecated/superseded repos):**
- Old lecture versions: `lecture-python`, `lecture-python-programming`, `lecture-python-advanced` (superseded by `.myst` versions)
- Deprecated infrastructure: themes, old build tools, test repos
- Inactive projects: old libraries, proposals, deprecated websites

**Schedule & Storage:**
- Weekly automated backups (Sunday 2 AM UTC)
- S3 Bucket: `backup-quantecon-github` (us-east-1)
- 88% test coverage

**Security:**
- Read-only GitHub operations (only downloads, never pushes)
- OIDC authentication for AWS (no long-lived secrets)
- Fine-grained PAT support for private repositories

**Status:** Production - Stable

---

## Recommended Next Steps

### Priority 1: Complete Testing & Deployment
1. **action-check-warnings**: Deploy to all 6 Python lecture repositories
2. **action-link-checker**: Expand from lecture-python-programming.myst to all lecture repos
3. **action-style-guide**: Extend from lecture-python-advanced.myst to remaining repositories

### Priority 2: Translation Pipeline
1. Deploy **action-translation** (sync mode) to English source repositories
2. Deploy **action-translation** (review mode) to Chinese translation repository
3. Set up Persian translation workflow with new Farsi glossary

### Priority 3: Monitoring & Documentation
1. Create centralized dashboard for action status across repositories
2. Document best practices for action configuration
3. Establish maintenance schedule for action updates

---

## Technical Notes

### Dependencies & Technologies
- **Claude AI Models:** Sonnet 4.5 (default for all AI-powered actions)
- **Languages:** TypeScript (action-translation), Python (style-guide, check-warnings, link-checker), Shell (weekly-report)
- **Frameworks:** GitHub Actions, MyST Markdown, Jupyter Book

### API & Cost Considerations
- Actions using Claude AI require `ANTHROPIC_API_KEY` secret
- Translation action includes cost estimation tools
- Style guide uses focused prompts to minimize token usage

---

## Contributors

The development of these actions has been supported by:
- [@mmcky](https://github.com/mmcky)
- [@HumphreyYang](https://github.com/HumphreyYang)
- [@nisha617](https://github.com/nisha617)

---

*This report was prepared for the QuantEcon End of Year 2025 Status Report.*


Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

QuantEcon GitHub Actions - End of Year Status Report 2025 #279

QuantEcon GitHub Actions - End of Year Status Report 2025

Executive Summary

Deployment Matrix: Python Lecture Series

Individual Action Details

1. Translation Action (`action-translation`)

2. Style Guide Checker (`action-style-guide`)

3. Weekly Report Action (`action-weekly-report`)

4. Check Warnings Action (`action-check-warnings`)

5. Link Checker Action (`action-link-checker`)

6. Repository Backup Workflow (`workflow-backups`)

Recommended Next Steps

Priority 1: Complete Testing & Deployment

Priority 2: Translation Pipeline

Priority 3: Monitoring & Documentation

Technical Notes

Dependencies & Technologies

API & Cost Considerations

Contributors

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Action	Current Version	Status	Development Stage
action-translation	v0.7.0	✅ Testing & Development	Active Development
action-style-guide	v0.5.1	✅ Testing & Development	Active Development
action-weekly-report	v2.2.0	✅ Deployed	Stable
action-check-warnings	v1.0.0	✅ Final Testing	Stable
action-link-checker	v1.0.0	✅ Final Testing	Stable
workflow-backups	v0.3.0	✅ Final Testing	Stable

Repository	Translation	Style Guide	Link Checker	Check Warnings	Weekly Report	Backups
lecture-python-programming.myst	-	-	✅ Testing	-	-	✅ 29 Dec 2025 (1)
lecture-python-advanced.myst	-	✅ Testing	-	-	-	✅ 29 Dec 2025 (6)
lecture-python-intro	-	-	-	-	-	✅ 29 Dec 2025 (6)
lecture-jax	-	-	-	-	-	✅ 29 Dec 2025 (1)
lecture-python.myst	-	-	-	-	-	✅ 29 Dec 2025 (6)
continuous_time_mcs	-	-	-	-	-	✅ 29 Dec 2025 (8)

Category	Repositories	Notes
Explicit Repos	`continuous_time_mcs`, `QuantEcon.manual`, `sphinx-tojupyter`, `lecture-wasm`, `lecture-python-advanced.myst`, `lecture-python-intro`, `lecture-python.myst`, `lecture-jax`, `lecture-python-programming.myst`	Test repos including largest lecture sites
*Pattern: `action-.`**	~5 repos	All GitHub Actions
*Pattern: `QuantEcon.`**	~11 repos	Core libraries (QuantEcon.py, QuantEcon.jl, etc.)

Profile	File	Purpose
Testing	`config.yml`	Current active config - selected test repos
Core	`config.quantecon-core.yml`	Essential assets only (libraries, active lectures, infrastructure)
Full	`config.quantecon-all.yml`	Complete org backup with all patterns

Uh oh!

QuantEcon GitHub Actions - End of Year Status Report 2025 #279

Description

QuantEcon GitHub Actions - End of Year Status Report 2025

Executive Summary

Deployment Matrix: Python Lecture Series

Individual Action Details

1. Translation Action (action-translation)

2. Style Guide Checker (action-style-guide)

3. Weekly Report Action (action-weekly-report)

4. Check Warnings Action (action-check-warnings)

5. Link Checker Action (action-link-checker)

6. Repository Backup Workflow (workflow-backups)

Recommended Next Steps

Priority 1: Complete Testing & Deployment

Priority 2: Translation Pipeline

Priority 3: Monitoring & Documentation

Technical Notes

Dependencies & Technologies

API & Cost Considerations

Contributors

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

1. Translation Action (`action-translation`)

2. Style Guide Checker (`action-style-guide`)

3. Weekly Report Action (`action-weekly-report`)

4. Check Warnings Action (`action-check-warnings`)

5. Link Checker Action (`action-link-checker`)

6. Repository Backup Workflow (`workflow-backups`)