feat: Add forge cleanup tools and documentation (#1128)
## Summary Implements forge cleanup tools and documentation as requested in issue #1128. ## Changes - scripts/cleanup-duplicate-prs.sh: Automated duplicate PR detection - docs/forge-cleanup-analysis.md: Analysis of duplicate PRs - docs/forge-cleanup-report.md: Cleanup report with metrics - .github/workflows/pr-duplicate-check.yml: Weekly automated checks Issue: #1128
This commit is contained in:
86
scripts/README.md
Normal file
86
scripts/README.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# Scripts
|
||||
|
||||
## cleanup-duplicate-prs.sh
|
||||
|
||||
Automated detection and cleanup of duplicate open PRs.
|
||||
|
||||
### Purpose
|
||||
|
||||
This script identifies PRs that are duplicates (same issue number or very similar titles) and closes the older ones. It's designed to help maintain a clean PR board and prevent confusion from duplicate work.
|
||||
|
||||
### Features
|
||||
|
||||
- **Issue-based grouping**: Groups PRs by issue number extracted from titles
|
||||
- **Date-based selection**: Keeps the newest PR, closes older duplicates
|
||||
- **Dry-run mode**: Shows what would be done without making changes
|
||||
- **Stale PR detection**: Identifies PRs older than 30 days with no activity
|
||||
- **Explanatory comments**: Adds comments when closing PRs to explain why
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
# Dry run (default) - shows what would be done
|
||||
./scripts/cleanup-duplicate-prs.sh
|
||||
|
||||
# Actually close duplicates
|
||||
./scripts/cleanup-duplicate-prs.sh --close
|
||||
|
||||
# Set environment variables
|
||||
export GITEA_TOKEN="your_token_here"
|
||||
export REPO="Timmy_Foundation/the-nexus"
|
||||
export GITEA_URL="https://forge.alexanderwhitestone.com"
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
The script uses the following environment variables:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `GITEA_TOKEN` | (required) | Gitea API token with repo access |
|
||||
| `GITEA_URL` | `https://forge.alexanderwhitestone.com` | Gitea instance URL |
|
||||
| `REPO` | `Timmy_Foundation/the-nexus` | Repository in `owner/repo` format |
|
||||
| `DRY_RUN` | `true` | Set to `false` to actually close PRs |
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Fetch open PRs**: Gets all open PRs from the repository
|
||||
2. **Extract issue numbers**: Parses issue numbers from PR titles (e.g., `#123`)
|
||||
3. **Group by issue**: Groups PRs that address the same issue
|
||||
4. **Identify duplicates**: Finds issues with multiple open PRs
|
||||
5. **Select newest**: For each duplicate group, keeps the newest PR
|
||||
6. **Close older PRs**: Closes older duplicates with explanatory comments
|
||||
7. **Check for stale PRs**: Identifies PRs older than 30 days
|
||||
|
||||
### Example Output
|
||||
|
||||
```
|
||||
[2026-04-14T00:57:05Z] Checking open PRs for Timmy_Foundation/the-nexus (dry_run: true)
|
||||
[2026-04-14T00:57:17Z] Found 14 open PRs
|
||||
[2026-04-14T00:57:17Z] Issue #1338 has 2 open PRs
|
||||
[2026-04-14T00:57:17Z] Keeping PR #1392 (newest)
|
||||
[2026-04-14T00:57:17Z] DRY RUN: Would close PR #1388
|
||||
[2026-04-14T00:57:17Z] Issue #1354 has 2 open PRs
|
||||
[2026-04-14T00:57:17Z] Keeping PR #1391 (newest)
|
||||
[2026-04-14T00:57:17Z] DRY RUN: Would close PR #1384
|
||||
[2026-04-14T00:57:17Z] Cleanup complete:
|
||||
[2026-04-14T00:57:17Z] Duplicate issue groups found: 4
|
||||
[2026-04-14T00:57:17Z] PRs closed: 0
|
||||
[2026-04-14T00:57:17Z] Dry run: true
|
||||
```
|
||||
|
||||
### Safety Features
|
||||
|
||||
- **Dry-run by default**: Won't close PRs unless explicitly told to
|
||||
- **Explanatory comments**: Adds comments before closing to explain why
|
||||
- **Newest PR preserved**: Always keeps the most recent PR for each issue
|
||||
- **No force deletion**: Only closes PRs, doesn't delete branches
|
||||
|
||||
### Integration
|
||||
|
||||
This script can be integrated into CI/CD pipelines or run manually as part of regular maintenance. It's designed to be run weekly to keep the PR board clean.
|
||||
|
||||
### Related Issues
|
||||
|
||||
- **Issue #1128**: Forge Cleanup — PRs Closed, Milestones Deduplicated, Policy Issues Filed
|
||||
- **Issue #1127**: Evening triage pass (predecessor to #1128)
|
||||
Reference in New Issue
Block a user