awesome-docker/AGENTS.md

Agent Guidelines for awesome-docker

Commands

• Build CLI: make build (or go build -o awesome-docker ./cmd/awesome-docker)
• Run tests: make test (runs go test ./internal/... -v)
• Lint README rules: make lint (runs ./awesome-docker lint)
• Auto-fix lint issues: ./awesome-docker lint --fix
• Check links: make check (runs ./awesome-docker check; GITHUB_TOKEN enables GitHub repo checks)
• PR validation: ./awesome-docker validate (lint + external link checks in PR mode)
• Build website: ./awesome-docker build (generates website/index.html from README.md)
• Health scoring: make health (requires GITHUB_TOKEN, updates config/health_cache.yaml)
• Generate health report: make report

Architecture

• Main content: README.md (curated Docker/container resources)
• CLI entrypoint: cmd/awesome-docker/main.go (Cobra commands)
• Core packages:
  • internal/parser - parse README sections and entries
  • internal/linter - alphabetical/order/format validation + autofix
  • internal/checker - HTTP and GitHub link checks
  • internal/scorer - repository health scoring and report generation
  • internal/cache - exclude list and health cache read/write
  • internal/builder - render README to website HTML from template
• Config:
  • config/exclude.yaml - known link-check exclusions
  • config/website.tmpl.html - HTML template for site generation
  • config/health_cache.yaml - persisted health scoring cache
• Website output: website/index.html

Code Style

• Language: Go
• Formatting: Keep code gofmt-clean
• Testing: Add/adjust table-driven tests in internal/*_test.go for behavior changes
• Error handling: Return wrapped errors (fmt.Errorf("context: %w", err)) from command handlers
• CLI conventions: Keep command behavior consistent with existing Cobra commands (lint, check, health, build, report, validate)

CI/Automation

• PR + weekly validation: .github/workflows/pull_request.yml
  • Triggers on pull requests to master and weekly schedule
  • Builds Go CLI and runs ./awesome-docker validate
• Weekly broken links issue: .github/workflows/broken_links.yml
  • Runs ./awesome-docker check
  • Opens/updates broken-links issue when failures are found
• Weekly health report issue: .github/workflows/health_report.yml
  • Runs ./awesome-docker health then ./awesome-docker report
  • Opens/updates health-report issue
• GitHub Pages deploy: .github/workflows/deploy-pages.yml
  • On push to master, builds CLI, runs ./awesome-docker build, deploys website/

Content Guidelines (from CONTRIBUTING.md)

• Use one link per entry
• Prefer project/repository URLs over marketing pages
• Keep entries alphabetically ordered within each section
• Keep descriptions concise and concrete
• Use :heavy_dollar_sign: only for paid/commercial services
• Remove archived/deprecated projects instead of tagging them
• Avoid duplicate links and redirect variants