awesome-docker/.github/MAINTENANCE.md

🔧 Maintenance Guide for Awesome Docker

This guide helps maintainers keep the awesome-docker list up-to-date and high-quality.

🤖 Automated Systems

Weekly Health Reports

• What: Checks all GitHub repositories for activity, archived status, and maintenance
• When: Every Monday at 9 AM UTC
• Where: Creates/updates a GitHub issue with label health-report
• Action: Review the report and mark abandoned projects with :skull:

Broken Links Detection

• What: Tests all links in README.md for availability
• When: Every Saturday at 2 AM UTC + on every PR
• Where: Creates/updates a GitHub issue with label broken-links
• Action: Fix or remove broken links, or add to exclusion list

PR Validation

• What: Checks for duplicate links and basic validation
• When: On every pull request
• Action: Automated - contributors see results immediately

📋 Manual Maintenance Tasks

Monthly Review (First Monday of the month)

1. Check health report issue for archived/stale projects
2. Mark archived projects with :skull: in README.md
3. Review projects with 2+ years of inactivity
4. Remove projects that are truly abandoned/broken

Quarterly Deep Dive (Every 3 months)

1. Run: ./awesome-docker health then ./awesome-docker report for detailed report
2. Review project categories - are they still relevant?
3. Check for popular new Docker tools to add
4. Update documentation links if newer versions exist

Annual Cleanup (January)

1. Remove all :skull: projects older than 1 year
2. Review CONTRIBUTING.md guidelines
3. Update year references in documentation

🛠️ Maintenance Commands

# Build the CLI
go build -o awesome-docker ./cmd/awesome-docker

# Lint README formatting (add --fix to auto-fix)
./awesome-docker lint
./awesome-docker lint --fix

# Check all links (requires GITHUB_TOKEN for GitHub repos)
./awesome-docker check

# PR validation (lint + external link check)
./awesome-docker validate

# Score repository health (requires GITHUB_TOKEN)
./awesome-docker health

# Generate health report from cache
./awesome-docker report

# Build the website
./awesome-docker build

# Run tests
go test ./...

📊 Quality Standards

Adding New Projects

• Must have clear documentation (README with install/usage)
• Should have activity within last 18 months
• GitHub project preferred over website links
• Must be Docker/container-related

Marking Projects as Abandoned

Use :skull: emoji when:

• Repository is archived on GitHub
• No commits for 2+ years
• Project explicitly states it's deprecated
• Maintainer confirms abandonment

Removing Projects

Only remove (don't just mark :skull:):

• Broken/404 links that can't be fixed
• Duplicate entries
• Spam or malicious projects
• Projects that never met quality standards

🚨 Emergency Procedures

Critical Broken Links

If important resources are down:

1. Check if they moved (update URL)
2. Search for alternatives
3. Check Internet Archive for mirrors
4. Temporarily comment out until resolved

Spam Pull Requests

1. Close immediately
2. Mark as spam
3. Block user if repeated offense
4. Don't engage in comments

📈 Metrics to Track

• Total projects: ~731 GitHub repos
• Health status: aim for <5% archived
• Link availability: aim for >98% working
• PR merge time: aim for <7 days
• Weekly contributor engagement

🤝 Getting Help

• Open a discussion in GitHub Discussions
• Check AGENTS.md for AI assistant guidelines
• Review CONTRIBUTING.md for contributor info

---

Last updated: 2025-10-01