feat: Add PR backlog management process (#1470)
## 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
This commit is contained in:
126
docs/pr-backlog-process.md
Normal file
126
docs/pr-backlog-process.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user