diff --git a/AGENTS.md b/AGENTS.md index f91ce68..4fa81ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,10 @@ # Agent Guidelines for awesome-docker +This is a curated list of projects for Docker. +**The projects has to be for Docker, not just using Docker.** + ## Commands + - Build CLI: `make build` (or `go build -o awesome-docker ./cmd/awesome-docker`) - Rebuild from scratch: `make rebuild` - Show local workflows: `make help` @@ -20,55 +24,29 @@ - Maintenance shortcut: `make workflow-maint` (health + JSON report file) ## 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 + - `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 + - `config/exclude.yaml` - known link-check exclusions + - `config/website.tmpl.html` - HTML template for site generation + - `config/health_cache.yaml` - persisted health scoring cache - **Generated outputs**: - - `awesome-docker` - compiled CLI binary - - `website/index.html` - generated website - - `HEALTH_REPORT.md` - generated markdown report - - `HEALTH_REPORT.json` - generated JSON report - -## 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/` - -## Makefile Workflow -- The `Makefile` models file dependencies for generated artifacts (`awesome-docker`, `website/index.html`, `config/health_cache.yaml`, `HEALTH_REPORT.md`, `HEALTH_REPORT.json`). -- Prefer `make` targets over ad-hoc command sequences so dependency and regeneration behavior stays consistent. -- Use: - - `make workflow-dev` for local iteration - - `make workflow-pr` before opening/updating a PR - - `make workflow-maint` for health/report maintenance - - `make workflow-ci` for CI-equivalent local checks + - `awesome-docker` - compiled CLI binary + - `website/index.html` - generated website + - `HEALTH_REPORT.md` - generated markdown report + - `HEALTH_REPORT.json` - generated JSON report ## Content Guidelines (from CONTRIBUTING.md) + +- **The projects has to be for Docker, not just using Docker.** - Use one link per entry - Prefer project/repository URLs over marketing pages - Keep entries alphabetically ordered within each section