38ce7e4bc5
## Summary Added tools and process for managing PR backlog in timmy-config. ## Problem timmy-config has 31+ open PRs, the highest in the organization. This creates confusion, slows down development, and increases merge conflicts. ## Solution Created automated tools and process for PR backlog management: ### 1. PR Backlog Analyzer (`scripts/pr-backlog-analyzer.py`) - Fetches all open PRs from timmy-config - Analyzes age, review status, labels - Generates markdown report - Categorizes PRs: stale, needs review, approved, changes requested ### 2. GitHub Actions Workflow (`.github/workflows/pr-backlog-management.yml`) - Runs weekly on Monday at 10 AM UTC - Analyzes PR backlog - Creates issue if backlog is high (>10 stale PRs) - Uploads report as artifact ### 3. Documentation (`docs/pr-backlog-process.md`) - Weekly analysis process - Review stale PRs procedure - Merge approved PRs workflow - Review pending PRs SLA - Close duplicate PRs process - Metrics to track - Escalation procedures ## Usage ### Run Analyzer ```bash python scripts/pr-backlog-analyzer.py ``` ### View Report ```bash cat reports/pr-backlog-$(date +%Y%m%d).md ``` ## Metrics - **Current**: 32 open PRs in timmy-config - **Target**: <20 open PRs - **SLA**: Review within 48 hours, merge within 7 days Issue: #1470
127 lines
3.4 KiB
Markdown
127 lines
3.4 KiB
Markdown
# PR Backlog Management Process
|
|
|
|
## Overview
|
|
|
|
This document outlines the process for managing PR backlog in the Timmy Foundation repositories, specifically addressing the high PR backlog in timmy-config.
|
|
|
|
## Current State
|
|
|
|
As of the latest analysis:
|
|
- **timmy-config**: 31 open PRs (highest in org)
|
|
- **the-nexus**: Multiple PRs for same issues
|
|
- **hermes-agent**: Moderate PR count
|
|
|
|
## Process
|
|
|
|
### 1. Weekly Analysis
|
|
|
|
Run the PR backlog analyzer weekly:
|
|
|
|
```bash
|
|
python scripts/pr-backlog-analyzer.py
|
|
```
|
|
|
|
This generates a report in `reports/pr-backlog-YYYYMMDD.md`.
|
|
|
|
### 2. Review Stale PRs
|
|
|
|
PRs older than 30 days are considered stale. For each stale PR:
|
|
|
|
1. **Check relevance**: Is the PR still needed?
|
|
2. **Check conflicts**: Does it conflict with current main?
|
|
3. **Check activity**: Has there been recent activity?
|
|
4. **Action**: Close, update, or merge
|
|
|
|
### 3. Merge Approved PRs
|
|
|
|
PRs with approvals should be merged within 7 days:
|
|
|
|
1. **Verify CI**: Ensure all checks pass
|
|
2. **Verify review**: At least 1 approval
|
|
3. **Merge**: Use squash merge for clean history
|
|
4. **Delete branch**: Clean up after merge
|
|
|
|
### 4. Review Pending PRs
|
|
|
|
PRs waiting for review should be reviewed within 48 hours:
|
|
|
|
1. **Assign reviewer**: Ensure someone is responsible
|
|
2. **Review**: Check code quality, tests, documentation
|
|
3. **Approve or request changes**: Don't leave PRs in limbo
|
|
4. **Follow up**: If no response in 48 hours, escalate
|
|
|
|
### 5. Close Duplicate PRs
|
|
|
|
Multiple PRs for the same issue should be consolidated:
|
|
|
|
1. **Identify duplicates**: Same issue number or similar changes
|
|
2. **Keep newest**: Usually the most up-to-date
|
|
3. **Close older**: With explanatory comments
|
|
4. **Document**: Update issue with which PR was kept
|
|
|
|
## Automation
|
|
|
|
### GitHub Actions Workflow
|
|
|
|
The `pr-backlog-management.yml` workflow runs weekly to:
|
|
|
|
1. Analyze all open PRs
|
|
2. Generate a report
|
|
3. Create an issue if backlog is high (>10 stale PRs)
|
|
|
|
### Manual Trigger
|
|
|
|
The workflow can be triggered manually via GitHub Actions UI.
|
|
|
|
## Metrics
|
|
|
|
Track these metrics weekly:
|
|
|
|
- **Total open PRs**: Should be <20 per repo
|
|
- **Stale PRs**: Should be <5 per repo
|
|
- **Average PR age**: Should be <14 days
|
|
- **Time to review**: Should be <48 hours
|
|
- **Time to merge**: Should be <7 days after approval
|
|
|
|
## Escalation
|
|
|
|
If backlog exceeds thresholds:
|
|
|
|
1. **Level 1**: Automated issue created
|
|
2. **Level 2**: Team lead notified
|
|
3. **Level 3**: Organization-wide cleanup sprint
|
|
|
|
## Tools
|
|
|
|
### PR Backlog Analyzer
|
|
|
|
```bash
|
|
# Run analysis
|
|
python scripts/pr-backlog-analyzer.py
|
|
|
|
# View report
|
|
cat reports/pr-backlog-$(date +%Y%m%d).md
|
|
```
|
|
|
|
### Manual Cleanup
|
|
|
|
```bash
|
|
# List stale PRs
|
|
curl -s -H "Authorization: token $GITEA_TOKEN" "https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/timmy-config/pulls?state=open" | jq -r '.[] | select(.created_at < "'$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ)'") | .number'
|
|
|
|
# Close a PR
|
|
curl -s -X PATCH -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" -d '{"state": "closed"}' "https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/timmy-config/pulls/123"
|
|
```
|
|
|
|
## Success Criteria
|
|
|
|
- **Short-term**: Reduce timmy-config PRs from 31 to <20
|
|
- **Medium-term**: Maintain <15 open PRs across all repos
|
|
- **Long-term**: Automated PR lifecycle management
|
|
|
|
## Related
|
|
|
|
- Issue #1470: process: Address timmy-config PR backlog (9 PRs - highest in org)
|
|
- Issue #1127: Evening triage pass
|
|
- Issue #1128: Forge Cleanup
|