ComDev Metrics Site — Execution Plan
Public, automated dashboard at community.apache.org/metrics/ showing activity of every Apache project with 12-month rolling trends.
Design Principles
- Trends, not absolutes — 12-month rolling window with linear regression trend lines
- Aggressive caching — past months are immutable; only the current month is refreshed
- Python/uv — anyone can clone and test locally with
uv run - Very configurable — a project can run it for just themselves
- VCS-agnostic — GitHub API by default, SVN for projects that use it
- Public — unlike Reporter, visible to everyone
- Static output — generated HTML + JS frontend, no live server
- JSON data store — collectors write JSON; frontend reads client-side
- No data duplication — link to projects.apache.org for project metadata
Data Domains
1. Mailing List Metrics
- Message volume (per-list, 12-month rolling window)
- Unique posters
- New-vs-returning poster ratio
- Response time (median time to first reply)
- Source: Pony Mail Foal API (
POST /api/stats.json) - Caching: Past months immutable; only current month re-fetched
2. Git/VCS Metrics
- Commits per month (12-month window)
- Unique committers per month
- PRs opened / merged / closed (GitHub only)
- Source: GitHub API (zero-checkout, API-only) OR
svn log --xml (remote, no checkout) - Auto-detection: SVN-only projects detected from
repositories.json - Per-project VCS config:
project_overrides in config.yml
3. Community Events
- PMC member additions
- New committers
- Releases published
- Source: projects.apache.org JSON, Whimsy roster, reporter.apache.org
4. Project Lifecycle
- New projects (graduated from Incubator)
- Retirements to Attic
- Source: Incubator status page, board minutes
Milestones
| # | Milestone | Target | Status |
|---|
| 1 | Scaffold project (pyproject.toml, config loading, CLI) | | ✅ Done |
| 2 | Mailing list collector (Pony Mail Foal API, 12-month window + caching) | | ✅ Done |
| 3 | Git/GitHub collector + SVN backend (per-repo, rate-limit aware) | | ✅ Done |
| 4 | Trend analysis (12-month rolling window + trend lines with current-month extrapolation) | | ✅ Done |
| 5 | Static HTML dashboard + per-project pages (default: All Projects tab) | | ✅ Done |
| 6 | Roster change detection (projects.apache.org JSON diffing) | | ✅ Done |
| 7 | Deploy to ComDev VM for demo | | ⬜ |
| 8 | Single-project self-serve mode | | ⬜ |
| 9 | Next Committer integration (PMC-only, LDAP gated) | | ⬜ |
| 10 | Production deployment on ComDev VM | | ⬜ |
Status: Dashboard running at https://boxofclue.com/comdev-metrics/
with 205 projects collecting successfully. Code at https://github.com/apache/comdev-metrics (pending).
Architecture Notes
Caching Strategy
- Mailing lists:
site/data/_cache/mailing_lists/<project>.json - Git activity:
site/data/_cache/git/<project>.json (per-repo monthly data) - Past months are immutable — data cannot change after a month ends
- Same-day re-runs skip (cache hit); next-day runs do incremental refresh from last fetch date
- Incremental refresh overlaps by re-fetching from the fetch date (not day-after) to avoid gaps
--force-refresh clears all caches--refresh-repos re-fetches the GitHub org repo inventory
Trend Lines
- Linear regression (least-squares) over the 12-month data series
- Current (incomplete) month is extrapolated to full-month projection before regression
- Extrapolation:
projected = actual × (days_in_month / day_of_month) - Rendered as dashed SVG overlay on per-project bar charts
Per-project Detail Pages
- Link to projects.apache.org for full metadata (roster, repos, homepage)
- No roster duplication — just show PMC size stat and link out
- Git section: clickable table of repos (sparklines), click to expand chart
- Mailing list section: same pattern — clickable list table, chart on click
- First/most-active item auto-expanded on page load
- Releases collapsed after 10 with “show more” expander
Rate Limiting (GitHub API)
- Tracks
x-ratelimit-remaining from every response - Auto-pauses and waits for reset when remaining ≤ 50
- Budget displayed inline every 20 projects + at end of git phase
Deployment
Development/Staging — boxofclue.com/comdev-metrics/
# Weekly cron
0 6 * * 1 rcbowen cd /home/rbowen/devel/apache/comdev/comdev-metrics && /usr/bin/uv run asfmetrics --config /home/rbowen/devel/apache/comdev/comdev-metrics/config.yml && rsync -az --delete site/ fagin.rcbowen.com:/var/www/vhosts/boxofclue.com/comdev-metrics/
Output served by httpd vhost pointing at site/.
Production — ComDev VM (Ubuntu)
Same cron pattern, output at community.apache.org/metrics/ (subdirectory or separate vhost — TBD).
Open Questions
| Question | Notes |
|---|
| Definitive data sources? | projects.a.o is secondary and may go away. Whimsy? LDAP? |
| Next Committer ↔ LDAP? | PMC-only access. Needs ASF Infra ticket for service account or OAuth. |
| Bot filtering? | Measure contributions by PMC, committers, everyone else — and bots separately |
| Static site hosting? | Subdirectory of community.apache.org? Separate vhost? |
Configuration
Lookup order:
./config.yml (project-local)~/.asfmetrics/config.yml (user-level)/etc/asfmetrics/config.yml (system-level, for ComDev VM)
See config.example.yml, .secrets.example, and DATA_SOURCES.md for details.