Regenerate January 2026 report with improved structure by castrojo · Pull Request #593 · projectbluefin/documentation

castrojo · 2026-01-27T14:11:27Z

Summary

This PR implements historical contributor detection to correctly identify new contributors when regenerating past reports. The previous approach used a cumulative history file which broke report regeneration.

🐛 Problem Fixed

The Bug: Cumulative history file broke report regeneration

Generate December report → Adds 20 contributors to history
Generate January report → Adds 24 contributors to history (cumulative: 44)
Regenerate December → Shows 0 new contributors (wrong! They were new in December)
Regenerate January → Shows wrong count (depends on generation order)

Root Cause: System answered the wrong question

❌ Old: "Has this person ever contributed before right now?"
✅ Correct: "Had this person contributed before this report's month started?"

✨ Solution: Query-Based Historical Detection

Instead of maintaining a cumulative file, query GitHub history at generation time to determine who was truly "new" relative to the report date.

How It Works:

For January 2026 report: Query all repos for PRs merged BEFORE January 1, 2026
Extract unique human contributors from historical period → historicalContributors
Extract contributors from January 2026 → currentContributors
New contributors = those in currentContributors but NOT in historicalContributors

Benefits:

✅ Regeneration-safe: Each report independently queries history relative to its own date
✅ Accurate: Correctly identifies first-time contributors for that specific month
✅ Idempotent: Running the same report multiple times produces identical results
✅ No state dependency: No shared state file that can get corrupted

📊 Changes

1. Implemented Historical Contributor Detection (0b8537d)

Added fetchContributorsBeforeDate() - queries GitHub for contributors before report date
Replaced updateContributorHistory() with identifyNewContributors()
Uses GitHub GraphQL API to fetch historical data (project start: 2024-01-01)
Performance: ~10 seconds additional per report (acceptable for monthly generation)

2. Enhanced Bot Filtering (0b8537d)

Added bot patterns: pull and testpullapp
These were incorrectly counted as human contributors
Now properly appear in "Bot Activity" section

3. Regenerated Reports with Accurate Counts (0b8537d)

December 2025: 14 new contributors (was 20, excluded 9 historical + 3 repeats)
January 2026: 10 new contributors (was 24, excluded December + historical)
Bot PRs properly separated: pull (8 PRs), testpullapp (5 PRs)

4. Added Technical Documentation (0b8537d)

.planning/technical-notes/contributor-detection-design.md
Explains problem, solution, algorithm, and testing strategy

5. Previous Commits (581c531, fc9f2ed, ef16ec4)

Fixed MDX build error (curly braces in PR titles)
Added --month=YYYY-MM CLI argument for regeneration
Applied planned vs opportunistic work structure
Restored New Contributors section with gold foil highlighting

🧪 Testing & Verification

✅ December 2025 Report

Historical contributors before Dec 1: 9
Contributors in December: 20
New contributors: 14
Math: 9 (historical) + 14 (new) - 3 (repeat) = 20 ✓

✅ January 2026 Report

Historical contributors before Jan 1: 23 (9 + 14 from Dec)
Contributors in January: 22
New contributors: 10
No overlap with December new contributors ✓

✅ Bot Filtering

pull (8 PRs) - now in Bot Activity section
testpullapp (5 PRs) - now in Bot Activity section
Removed from human contributor counts

✅ Regeneration Test

Generated December report: 14 new contributors
Generated January report: 10 new contributors
Re-generated December: Still 14 new contributors (idempotent!) ✓

✅ Build & Serve

npm run build - passes
npm run start - dev server runs
npm run serve - production build works
Reports display correctly at /reports/

📈 Performance

Report generation time: ~20 seconds total
- Report period query: ~8 seconds (8 repos)
- Historical query: ~10 seconds (8 repos)
Well within acceptable limits for monthly generation
Accuracy prioritized over speed

🔗 Related

Fixes report regeneration bug discovered during January 2026 report work
Applies improvements from feat(reports): split monthly reports into planned vs opportunistic work #586 (planned vs opportunistic split)
Applies improvements from Use projectbluefin/common for planned work tracking #587 (projectbluefin/common integration)
Addresses contributor tracking reliability concerns

Commits: 4 total (1 historical detection + 1 contributor fix + 1 structure + 1 planning)
Type: Bug fix + enhancement
Impact: Enables accurate historical reporting and reliable regeneration

Regenerate January 2026 monthly report to include structural improvements: - Split categories into Planned vs Opportunistic subsections - Use projectbluefin/common for planned work tracking - Separate Focus Area (area/ labels) from Work by Type (kind/ labels) - Apply proper bot filtering and contributor tracking - Fix MDX curly brace escaping in PR titles to prevent build errors Script improvements: - Add --month=YYYY-MM CLI argument for report regeneration - Escape curly braces in PR/issue titles to prevent MDX/JSX parsing errors - Applied fix to all formatItemList functions in markdown generator Previous report was generated before PRs #586 and #587 were merged. This regeneration brings the January report up to date with current format. Fixes MDX build error: "boot is not defined" caused by unescaped curly braces in PR titles like "/{boot,tmp}" being interpreted as JSX. Refs: #586, #587

…provements made to the report structure and subsections Quick task completed. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…hting The January 2026 report was missing the New Contributors section because the contributor history file already contained all January contributors from the initial generation. Fixed by: - Deleting contributor history baseline to reset detection - Regenerating January 2026 report with fresh contributor tracking - All 24 contributors now correctly identified as new for January - Gold foil effect (highlight={true}) applied to all new contributor cards Verified: - Build passes successfully - New Contributors section renders with 24 profile cards - All cards have highlight={true} prop and gold foil CSS styling - Regular Contributors section also displays all 24 contributors Note: contributors-history.json is auto-generated and gitignored per design Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

… report regeneration Replace cumulative history file with GitHub query-based detection to correctly identify new contributors relative to report date. This fixes regeneration issues where past reports would incorrectly show zero new contributors. Changes: - Add fetchContributorsBeforeDate() to query historical GitHub data - Replace updateContributorHistory() with identifyNewContributors() - Add bot patterns for 'pull' and 'testpullapp' automation - Regenerate December 2025 and January 2026 reports with accurate counts - Add technical design documentation Bot activity now properly separated from human contributions.

… ChillOps for empty ones Previously, if a subsection was empty it would be omitted entirely. Now both subsections always display, showing '> Status: ChillOps' when empty. This provides consistent structure across all categories and makes it clear when there was no activity in a particular work type. Changes: - Always show '📋 Planned Work' subsection (with ChillOps if empty) - Always show '⚡ Opportunistic Work' subsection (with ChillOps if empty) - Regenerate December and January reports with consistent structure

Update planning documents to reflect v1.1 completion and current project state: STATE.md: - Update status to SHIPPED + Post-Launch Improvements - Add PR #593 accomplishments (historical detection, ChillOps) - Update performance metrics with actual results - Update decisions table with query-based detection - Update architecture section with shipped files - Mark Phase 3 as deferred (goal met via AGENTS.md) - Update session continuity for new milestone planning MILESTONES.md: - Mark v1.1 as SHIPPED (2026-01-27) - List key accomplishments and stats - Add post-launch improvements note - Update git range and timeline ROADMAP.md: - Mark all phases with SHIPPED status - Add post-launch improvements section - Update automation schedule (monthly, last day) - Update metrics with actual results - Add deferred Phase 3 explanation - Update timeline with actual vs estimated New file: milestones/v1.1-COMPLETION.md: - Executive summary of milestone delivery - Detailed deliverables for all phases - Post-launch improvements documentation - Metrics and performance data - Reports published (December, January) - Technical achievements and data flow - Lessons learned and future considerations - Complete artifact listing All documents now accurately reflect the shipped v1.1 milestone and are ready for next planning cycle.

castrojo and others added 5 commits January 27, 2026 09:04

docs(quick-002): continue regenerating the january report with the im…

ef16ec4

…provements made to the report structure and subsections Quick task completed. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

castrojo merged commit 2c4f7f6 into main Jan 27, 2026
2 checks passed

castrojo deleted the quick/regenerate-january-report-improved branch January 27, 2026 14:35

castrojo added the kind/automation CI/CD workflows, scripts, and automation tooling label Jan 29, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Regenerate January 2026 report with improved structure#593

Regenerate January 2026 report with improved structure#593
castrojo merged 5 commits intomainfrom
quick/regenerate-january-report-improved

castrojo commented Jan 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

castrojo commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

🐛 Problem Fixed

✨ Solution: Query-Based Historical Detection

📊 Changes

🧪 Testing & Verification

📈 Performance

🔗 Related

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

castrojo commented Jan 27, 2026 •

edited

Loading