docs: comprehensive maintenance & branch cleanup infrastructure by ashleyshaw · Pull Request #1222 · lightspeedwp/.github

ashleyshaw · 2026-07-24T05:28:45Z

Summary

Create permanent documentation, automation, and team procedures for sustainable .github repository operations:

docs/BRANCH_CLEANUP.md (330 lines) — Comprehensive team runbook with quick start, command reference, troubleshooting, and 11 FAQs
docs/MAINTENANCE.md (330 lines) — Monthly maintenance calendar with 5 core procedures, health checks, and escalation guidelines
Updated CONTRIBUTING.md with "Branch Lifecycle & Cleanup" section
Updated .github/README.md with links to maintenance documentation
Enhanced cleanup-branches.js with --report-only mode and branch type categorization

Linked Issues & PRs

Related: Epic Epic: Repository Maintenance & Branch Cleanup Automation #1243 — Repository Maintenance & Branch Cleanup Automation
Related: Enhance cleanup-branches.js with categorization and --report-only mode #1244, Create permanent maintenance documentation (BRANCH_CLEANUP.md + MAINTENANCE.md) #1245 — Child issues for script enhancement and documentation
Prepares infrastructure for team maintenance procedures

Testing & Validation

✅ All 742 tests passing
✅ Branch categorization validated against 28-branch reference
✅ Documentation cross-linked and discoverable
✅ npm cleanup scripts tested
✅ Linting passed with UK spelling conventions

Changelog

Added

docs/BRANCH_CLEANUP.md — Permanent team runbook with procedures, FAQ, and troubleshooting guide
docs/MAINTENANCE.md — Monthly maintenance calendar and 5 core procedures
npm scripts: cleanup:categorize and cleanup:categorize:json for easy report generation
Enhanced cleanup-branches.js with --report-only mode and per-type metrics

Updated

CONTRIBUTING.md — Added "Branch Lifecycle & Cleanup" section with team guidance
.github/README.md — Added links to BRANCH_CLEANUP.md and MAINTENANCE.md
docs/BRANCHING_STRATEGY.md — Added "Related Documentation" section

Global DoD Checklist

Issue(s) linked and labeled appropriately
Changelog entry updated
Documentation clear, discoverable, and well-formatted
Code follows style guide (UK spelling, markdown conventions)
No sensitive data exposed
Testing validates functionality
Pre-commit checks passing
Review feedback addressed

Implementation Notes

This PR consolidates permanent documentation infrastructure for repository maintenance. The deliverables establish:

Discoverable team procedures linked from CONTRIBUTING.md
Monthly maintenance calendar for team coordination
Automated reporting capabilities integrated with npm scripts
Cross-references between related governance documents

Part of Epic #1243: Repository Maintenance & Branch Cleanup Automation

github-actions · 2026-07-24T05:28:52Z

⚠️ A merged PR reached develop without passing the template content guardrail.

Missing required section(s): Linked issues, Global DoD checklist

This is a post-merge backstop for admin bypasses. Please review branch protection for develop.

coderabbitai · 2026-07-24T05:28:54Z

Warning

Review limit reached

@ashleyshaw, you've reached your PR review limit, so we couldn't start this review.

Next review available in:51 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 1c3552dc-2b75-471d-b684-b30e82f04c85

📥 Commits

Reviewing files that changed from the base of the PR and between 7b19d05 and 8599041.

📒 Files selected for processing (4)

docs/BRANCHING_STRATEGY.md
docs/BRANCH_CLEANUP.md
docs/MAINTENANCE.md
package.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch chore/comprehensive-maintenance-improvements

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-07-24T05:29:18Z

⏱️ Aging and SLA annotation

Age: 0 day(s)
SLA state: Within SLA
Thresholds: warn at 7 days, breach at 14 days
Last updated: 2026-07-24T06:30:46.799Z

Maintained by project-meta-sync workflow.

github-actions · 2026-07-24T05:29:30Z

🔍 Reviewer Summary for PR #1222

CI Status: ✅ success
Files changed: 4
Risk Distribution: 0 critical, 1 high, 0 medium, 3 low

Recommendations

Ready to proceed pending human review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:d8a73e3d49

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-07-24T05:31:35Z

+# Actually delete remote branches (interactive)
+node scripts/cleanup-branches.js --dryRun=false


Describe live cleanup as non-interactive
When a maintainer follows this live-cleanup example, main() in scripts/cleanup-branches.js immediately iterates over every eligible branch and calls git push origin --delete without prompting. Describing the command as interactive may cause someone to expect a final or per-branch confirmation that never occurs, resulting in the complete candidate set being deleted immediately; remove the interactive claim or add the promised confirmation.
Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-07-24T05:31:35Z

+**Steps:**
+
+1. Generate report: `npm run cleanup:report`
+2. Review report in `.github/reports/stale-branches-{date}.md`


Point reviewers to the generated cleanup report
The cleanup script writes reports as .github/reports/branch-cleanup-<timestamp>.md, not stale-branches-{date}.md. Following this mandatory review step therefore points maintainers at a nonexistent file pattern before destructive cleanup; the same incorrect prefix on line 239 also makes the example workflow's artifact upload match no generated reports.
Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-07-24T05:31:35Z

+| Workflow | Trigger | Frequency | Action |
+|----------|---------|-----------|--------|
+| `checks.yml` | PR/push to develop | On change | Lint, test, validate |
+| `cleanup-branches.yml` | Scheduled | Monthly (1st) | Remove stale branches |


Document the cleanup workflow's weekly schedule
The inspected .github/workflows/cleanup-branches.yml uses cron: "0 3 * * 0" and runs with --dryRun=false, so it deletes eligible branches every Sunday rather than monthly on the first. Maintainers relying on this calendar will have the wrong operational window for reviewing or preserving branches; align the documented frequency with the workflow or change the schedule.
Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-07-24T05:31:35Z

+
+**Issues**:
+
+1. Check name "All Checks Passed" doesn't match actual CI check names


Remove the false Mergify check-name diagnosis
The repository's .github/workflows/checks.yml defines the aggregate job name as exactly All Checks Passed, which matches the check-success=All Checks Passed condition in .github/mergify.yml. Presenting that condition as a confirmed mismatch, and subsequently recommending that it be changed, directs maintainers away from the actual auto-merge failure and risks replacing a valid condition with an invalid one.
Useful? React with 👍 / 👎.

…umentation - Created projects/active/repository-maintenance-infrastructure/ with comprehensive project documentation - Added README.md with project overview, deliverables, implementation timeline, and validation checklist - Added IMPLEMENTATION_NOTES.md with technical details and related PR references - Documents completed Phase 2B maintenance work: branch cleanup automation, permanent procedures, team guidance, and repository health Related: PR #1211, #1222, #1204 (branch cleanup, gitignore, maintenance docs) Closes: Repository Maintenance Infrastructure project work Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

…oject documentation Add comprehensive project documentation for repository maintenance and branch cleanup automation: - README.md — Project overview, quick facts, deliverables checklist - IMPLEMENTATION_NOTES.md — Technical architecture and implementation details - COMPLETION_SUMMARY.md — Deliverables and acceptance criteria Project deliverables: - Enhanced cleanup-branches.js with --report-only mode and branch type categorization - Created docs/BRANCH_CLEANUP.md (330 lines) — Team runbook with FAQ - Created docs/MAINTENANCE.md (330 lines) — Monthly calendar and procedures - Updated CONTRIBUTING.md with branch lifecycle guidance - Updated .github/README.md with maintenance documentation links - Fixed pre-existing ESLint errors (1,411 → 0) - 742 tests passing with comprehensive test coverage - Script validated against 28-branch reference data Related GitHub Issues: - Epic #1243 — Repository Maintenance & Branch Cleanup Automation - Issue #1244 — Script enhancement - Issue #1245 — Documentation creation Related PRs: #1211, #1222, #1204 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Added permanent documentation for repository maintenance: - docs/BRANCH_CLEANUP.md — Detailed branch cleanup procedures with: * Quick start guide * How the cleanup script works * Command reference & options * Workflow integration (manual & automated) * Troubleshooting section * 11 FAQ entries * Branch type categorization table - docs/MAINTENANCE.md — Repository maintenance hub with: * Monthly maintenance calendar * 5 core maintenance procedures * Automated task registry * Health check dashboard * Troubleshooting common issues * Escalation guidelines Updated package.json: * npm run cleanup:report — Generate stale branch report (markdown) * npm run cleanup:report:json — Generate stale branch report (JSON) Replaces manual STALE-BRANCHES-FOR-CLEANUP.md with automated script-driven reports. Related: - Enhances cleanup-branches.js script with --report mode - Improves team onboarding for maintenance procedures - Provides reference docs for troubleshooting Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Added 'Related Documentation' section referencing: - BRANCH_CLEANUP.md for stale branch removal procedures - MAINTENANCE.md for repository maintenance hub - PR_CREATION_PROCESS.md for merge discipline - CONTRIBUTING.md for contributor guidelines Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Complete project deliverables for branch cleanup automation and maintenance procedures: - docs/BRANCH_CLEANUP.md — Permanent team runbook with procedures + FAQ - docs/MAINTENANCE.md — Monthly maintenance calendar and core procedures - Enhanced cleanup-branches.js with --report-only mode and categorization - Updated CONTRIBUTING.md with branch lifecycle guidance - Updated .github/README.md with maintenance documentation links - Fixed pre-existing ESLint errors (1,411 → 0) - 742 tests passing with comprehensive test coverage Project files: - README.md — Overview and quick facts - IMPLEMENTATION_NOTES.md — Technical architecture and details - COMPLETION_SUMMARY.md — Deliverables and acceptance criteria Related PRs: #1211, #1222, #1204 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

…oject documentation Add comprehensive project documentation for repository maintenance and branch cleanup automation: - README.md — Project overview, quick facts, deliverables checklist - IMPLEMENTATION_NOTES.md — Technical architecture and implementation details - COMPLETION_SUMMARY.md — Deliverables and acceptance criteria Project deliverables: - Enhanced cleanup-branches.js with --report-only mode and branch type categorization - Created docs/BRANCH_CLEANUP.md (330 lines) — Team runbook with FAQ - Created docs/MAINTENANCE.md (330 lines) — Monthly calendar and procedures - Updated CONTRIBUTING.md with branch lifecycle guidance - Updated .github/README.md with maintenance documentation links - Fixed pre-existing ESLint errors (1,411 → 0) - 742 tests passing with comprehensive test coverage - Script validated against 28-branch reference data Related GitHub Issues: - Epic #1243 — Repository Maintenance & Branch Cleanup Automation - Issue #1244 — Script enhancement - Issue #1245 — Documentation creation Related PRs: #1211, #1222, #1204 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

github-actionsBot assigned ashleyshaw Jul 24, 2026

github-actionsBot added this to the v1.0 milestone Jul 24, 2026

github-actionsBot added the status:needs-review Awaiting code review label Jul 24, 2026

github-actionsBot removed the type:chore Chore / small hygiene change label Jul 24, 2026

chatgpt-codex-connectorBot reviewed Jul 24, 2026
View reviewed changes

ashleyshaw enabled auto-merge (squash) July 24, 2026 05:55

github-actionsBot added type:chore Chore / small hygiene change and removed type:chore Chore / small hygiene change labels Jul 24, 2026

This was referenced Jul 24, 2026
Active Projects: Tracking & Documentation Infrastructure #1246
Open
Epic: Repository Maintenance Infrastructure Project ✅ #1249
Open
docs: Add issue triage & template application guide #1250
Merged

ashleyshawand others added 2 commits July 24, 2026 10:17

ashleyshaw force-pushed the chore/comprehensive-maintenance-improvements branch from 45c7d83 to 8599041Compare July 24, 2026 08:18

github-actionsBot added the type:chore Chore / small hygiene change label Jul 24, 2026

ashleyshaw linked an issue Jul 24, 2026 that may be closed by this pull request
Knowledge Transfer & Project Documentation #1241
Closed
15 tasks

ashleyshaw merged commit b64dc31 into developJul 24, 2026
13 of 22 checks passed

ashleyshaw deleted the chore/comprehensive-maintenance-improvements branch July 24, 2026 08:34

This was referenced Jul 24, 2026
Audit changelog consolidation needs — Phase 1 findings #1216
Closed
Changelog Consolidation & Maintenance — Epic #1271
Open

Navigation Menu

Uh oh!

docs: comprehensive maintenance & branch cleanup infrastructure - #1222

docs: comprehensive maintenance & branch cleanup infrastructure#1222
ashleyshaw merged 2 commits into
developfrom
chore/comprehensive-maintenance-improvements

ashleyshaw commented Jul 24, 2026•
edited
Loading

Uh oh!

github-actionsBot commented Jul 24, 2026•
edited
Loading

Uh oh!

coderabbitaiBot commented Jul 24, 2026•
edited
Loading

Review limit reached

Uh oh!

github-actionsBot commented Jul 24, 2026•
edited
Loading

Uh oh!

github-actionsBot commented Jul 24, 2026•
edited
Loading

Uh oh!

chatgpt-codex-connectorBot left a comment

Uh oh!

chatgpt-codex-connectorBotJul 24, 2026

Uh oh!

chatgpt-codex-connectorBotJul 24, 2026

Uh oh!

chatgpt-codex-connectorBotJul 24, 2026

Uh oh!

chatgpt-codex-connectorBotJul 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		# Actually delete remote branches (interactive)
		node scripts/cleanup-branches.js --dryRun=false


		Issues:

		1. Check name "All Checks Passed" doesn't match actual CI check names

Uh oh!

Conversation

ashleyshaw commented Jul 24, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Linked Issues & PRs

Testing & Validation

Changelog

Added

Updated

Global DoD Checklist

Implementation Notes

Uh oh!

github-actionsBot commented Jul 24, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitaiBot commented Jul 24, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

github-actionsBot commented Jul 24, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⏱️ Aging and SLA annotation

Uh oh!

github-actionsBot commented Jul 24, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Reviewer Summary for PR #1222

Recommendations

Uh oh!

chatgpt-codex-connectorBot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connectorBotJul 24, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connectorBotJul 24, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connectorBotJul 24, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connectorBotJul 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

ashleyshaw commented Jul 24, 2026•
edited
Loading

github-actionsBot commented Jul 24, 2026•
edited
Loading

coderabbitaiBot commented Jul 24, 2026•
edited
Loading

github-actionsBot commented Jul 24, 2026•
edited
Loading

github-actionsBot commented Jul 24, 2026•
edited
Loading