Onboarding: avelino/awesome-go

Generated by RepoPilot · 2026-05-05 · Source

Verdict

GO — Healthy across the board

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 35%)
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

awesome-go is a community-curated README.md and companion website (awesome-go.com) listing high-quality Go frameworks, libraries, and tools organized by category. The repo is not a library itself — it is a static-site generator that parses README.md (Markdown), validates every linked GitHub repository for health metrics, and renders an HTML site via Go templates. The core problem it solves is helping Go developers discover vetted, maintained packages without manually searching pkg.go.dev. Single-package Go binary at main.go that reads README.md, converts Markdown to HTML via pkg/markdown/convert.go (goldmark), generates URL slugs via pkg/slug/generator.go, copies static assets from tmpl/assets/, and writes the site output. CI tooling lives as separate main packages under .github/scripts/check-pr-diff/ and .github/scripts/check-quality/.

Who it's for

Go developers at any experience level who want to discover libraries for a specific domain (e.g. HTTP routers, ORMs, CLI frameworks). Secondary audience is open-source maintainers who want their Go library indexed. Contributors are typically Go devs who find a missing or stale entry and submit a PR to README.md.

Maturity & risk

The repo has a full CI pipeline (.github/workflows/tests.yaml, pr-quality-check.yaml, run-check.yaml), automated PR diff checks (.github/scripts/check-pr-diff/main.go), and is actively deployed to Netlify on every merge. The go.mod targets Go 1.23 with a 1.24.1 toolchain and all direct dependencies have recent versions. This is a production-running, actively maintained project — not experimental.

Primary maintainer risk is real: the repo is under the single avelino GitHub account with a small MAINTAINERS file. Dependency surface is minimal (5 direct deps: goquery, slugify, otiai10/copy, goldmark, oauth2) so supply-chain risk is low. The main operational risk is that GitHub API rate limits (OAuth2 via golang.org/x/oauth2) can silently cause false 'stale' verdicts during CI checks if the GITHUB_TOKEN env var is missing.

Active areas of work

Active work is focused on automated quality enforcement: .github/workflows/pr-quality-check.yaml runs check-quality and check-pr-diff on every PR to reject low-quality or spammy additions. The recheck-open-prs.yaml workflow periodically re-evaluates open PRs against freshness rules. AGENTS.md and .github/copilot-instructions.md suggest recent investment in AI-assisted contribution workflows.

Get running

git clone https://github.com/avelino/awesome-go.git && cd awesome-go && go mod download && go run main.go

To run tests:

go test ./...

To run the PR quality checker locally:

cd .github/scripts/check-quality && go run main.go

Daily commands: go run main.go — this parses README.md and writes the static site to the output directory. For tests: go test ./... — covers main_test.go (link validation), maturity_test.go (repo maturity checks), stale_repositories_test.go, pkg/markdown/convert_test.go, and pkg/slug/generator_test.go.

Map of the codebase

• main.go — Entry point that orchestrates the full site generation pipeline: parses README.md, fetches GitHub metadata, and renders HTML templates.
• README.md — The authoritative data source — every Go library entry, category, and description lives here and is parsed at build time.
• pkg/markdown/convert.go — Core abstraction that converts the README markdown into structured data (categories, links, descriptions) consumed by the site generator.
• tmpl/index.tmpl.html — Primary HTML template for the generated site homepage; changes here affect every visitor's experience.
• .github/scripts/check-quality/main.go — Automated quality-gate script that validates PR entries meet contribution standards before merge.
• .github/workflows/tests.yaml — CI pipeline definition that runs all tests and quality checks — the gatekeeper for every change to main.
• go.mod — Defines the module identity and all external dependencies (goldmark, goquery, oauth2) that the build and checks rely on.

Components & responsibilities

• main.go (Go stdlib (html/template, net/http), golang.org/x/oauth2) — Orchestrates the entire build: reads README, invokes markdown parser, calls GitHub API, executes templates, writes output files.
  • Failure mode: GitHub API rate

How to make changes

Add a new Go library entry to an existing category

1. Find the appropriate category section in the main data file and add a markdown list item: - [LibName](https://github.com/org/repo) - Short description. (README.md)
2. Run the quality check script locally to verify your entry passes URL reachability, description presence, and alphabetical ordering rules. (.github/scripts/check-quality/main.go)
3. Run tests to confirm the markdown parser correctly picks up your new entry without breaking existing structure. (pkg/markdown/convert_test.go)

Add a new category to the curated list

1. Add a new H2 or H3 heading and initial list entries in alphabetical order relative to surrounding categories. (README.md)
2. Verify the slug generator produces a valid, collision-free URL slug for the new heading text. (pkg/slug/generator.go)
3. Update or review the category index template if the new category needs custom rendering logic. (tmpl/category-index.tmpl.html)
4. Add a test case asserting the new category appears in the parsed output. (pkg/markdown/convert_test.go)

Add a new static site page template

1. Create a new .tmpl.html file in the tmpl directory following the existing template conventions (e.g., shared CSS imports, nav structure). (tmpl/project.tmpl.html)
2. Register and render the new template in the site generator, passing the appropriate data struct. (main.go)
3. Add the new page URL to the sitemap template so search engines can discover it. (tmpl/sitemap.tmpl.xml)

Add or update a CI quality check

1. Implement the new validation rule in the check-quality script, returning a non-zero exit code on failure. (.github/scripts/check-quality/main.go)
2. If checking PR diff content, add logic to the PR diff checker script. (.github/scripts/check-pr-diff/main.go)
3. Reference the updated script in the workflow trigger file to ensure it runs on every PR. (.github/workflows/run-check.yaml)

Why these technologies

• Go (static site generator) — The repo maintainers are Go experts; using Go to generate the site keeps tooling uniform and avoids a separate build ecosystem like Node.
• goldmark (markdown parser) — CommonMark-compliant, extensible, and actively maintained — parses README.md reliably into an AST for structured data extraction.
• goquery — jQuery-like HTML traversal for post-processing rendered HTML, enabling link extraction and validation without regex hacks.
• Netlify (static hosting) — Zero-ops CDN hosting for the generated static site with automatic HTTPS and deploy previews for PRs.
• GitHub Actions — Native integration with the GitHub PR workflow enables automated quality gates without external CI services.

Trade-offs already made

• README.md as the single source of truth

  • Why: Simplifies contribution — editors only touch one file; no database or CMS required.
  • Consequence: Parsing logic must be robust against human formatting errors; malformed markdown can silently drop entries.

• Static site generation at deploy time

  • Why: Eliminates runtime servers, scaling concerns, and attack surface.
  • Consequence: GitHub API data (stars, last commit) is only as fresh as the last deploy; no real-time updates.

• GitHub API called serially/in parallel at build time

  • Why: Enriches entries with live repo stats without requiring contributors to maintain numbers manually.
  • Consequence: Unauthenticated builds hit GitHub's 60 req/hr rate limit quickly; CI must use a token secret.

• Quality checks as standalone Go binaries in .github/scripts

  • Why: Keeps CI logic version-controlled, testable, and language-consistent with the rest of the repo.
  • Consequence: Each script must be compiled during CI, adding a small overhead vs. shell scripts.

Non-goals (don't propose these)

• Real-time or user-submitted library listings — all entries are manually curated via PR.
• Full-text search backend — the site is purely static with no server-side query handling.
• Automated discovery or crawling of new Go libraries.
• User accounts, authentication, or personalization features.
• Versioned snapshots of the list over time.

Traps & gotchas

1. GITHUB_TOKEN must be set as an env var for stale_repositories_test.go and maturity_test.go to work — without it, GitHub API calls will be rate-limited to 60 req/hr and tests will produce false failures. 2. README.md entries MUST follow the exact format '- Name - Description.' (dash, bracketed name, URL, dash, sentence ending in period) — check-pr-diff enforces this strictly and will fail PRs that deviate. 3. The go.mod specifies toolchain go1.24.1 explicitly; using an older toolchain may cause 'toolchain' directive errors with Go 1.23 builds.

Architecture

Concepts to learn

• Static site generation from Markdown — The entire awesome-go website is built by parsing README.md at build time with goldmark — understanding this pipeline (main.go → pkg/markdown/convert.go → HTML output) is essential to modifying the site.
• GitHub REST API rate limiting — stale_repositories_test.go and maturity_test.go make GitHub API calls that hit a 60 req/hr unauthenticated limit; the repo uses golang.org/x/oauth2 to authenticate and raise this to 5000 req/hr.
• Pull request diff validation — .github/scripts/check-pr-diff/main.go parses the raw unified diff of a PR to enforce structural rules on README.md changes — a non-obvious CI pattern unique to curated list repos.
• Repository maturity heuristics — maturity_test.go applies scoring rules (star count, last commit date, open issues ratio) to decide if a linked repo is 'healthy enough' — understanding these thresholds explains why some PRs get rejected.
• URL slug generation — pkg/slug/generator.go converts Markdown heading text into stable, URL-safe fragment identifiers (#audio-and-music) used for site navigation — bugs here break all anchor links.
• Netlify continuous deployment — site-deploy.yaml triggers a Netlify build on every main branch push; the netlify.toml config controls build commands and publish directory — relevant if the site stops updating after a merge.

Related repos

• sindresorhus/awesome — The original 'awesome list' format and badge that awesome-go follows; defines the meta-standard for all awesome-* repos.
• avelino/awesome-go — Self-referential: this is the canonical repo being described.
• dgryski/awesome-go-perf — A narrower Go-focused curated list covering only performance libraries, often cross-referenced with awesome-go entries.
• gobuffalo/awesome-buffalo — A curated list for the Buffalo Go web framework ecosystem — a subset domain that awesome-go also covers.
• yuin/goldmark — The Markdown parser library directly imported in go.mod and used in pkg/markdown/convert.go for site generation.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for pkg/slug/generator.go edge cases (unicode, special chars, consecutive hyphens)

The file pkg/slug/generator_test.go exists but slug generation for awesome-go is critical because slugs are used to generate anchor links on awesome-go.com. Any missed edge case (e.g. Go library names with dots like 'net/http', parentheses, unicode characters, or consecutive hyphens) can produce broken anchor links site-wide. Expanding test coverage here directly protects the site's navigation reliability.

• [ ] Open pkg/slug/generator.go and enumerate all slug transformation rules (lowercasing, special char stripping, hyphen collapsing, etc.)
• [ ] Open pkg/slug/generator_test.go and identify which edge cases are NOT yet covered (e.g. input with '/', '.', '()', unicode letters, leading/trailing hyphens, consecutive hyphens)
• [ ] Add table-driven test cases in pkg/slug/generator_test.go for each missing edge case using Go's testing package
• [ ] Run 'go test ./pkg/slug/...' to confirm all new cases pass or expose real bugs to fix
• [ ] If bugs are found in generator.go during this process, fix them in the same PR with a corresponding regression test

Add unit tests for .github/scripts/check-pr-diff/main.go to cover allowed and disallowed diff patterns

The check-pr-diff script is a critical gate that validates every incoming PR to awesome-go, yet there is no test file alongside .github/scripts/check-pr-diff/main.go. If the diff-checking logic has a bug, either valid PRs get incorrectly rejected (contributor friction) or spammy/low-quality PRs slip through (list quality degrades). Adding a main_test.go in that package with concrete diff fixture inputs would directly protect the repo's PR quality gate.

• [ ] Read .github/scripts/check-pr-diff/main.go thoroughly to understand what diff patterns it accepts and rejects (e.g. only README.md changes, single entry additions, etc.)
• [ ] Create .github/scripts/check-pr-diff/main_test.go with table-driven tests covering: a valid single-entry addition diff, a diff touching non-README files, a diff adding multiple entries, and an empty diff
• [ ] Refactor any logic in main.go that is inside main() into exported or unexported helper functions so they can be unit tested without subprocess invocation
• [ ] Run 'go test ./github/scripts/check-pr-diff/...' and ensure all cases pass
• [ ] Update .github/workflows/tests.yaml to include this new test package in the test run if it is not already covered by a wildcard

Add unit tests for .github/scripts/check-quality/main.go covering URL liveness and metadata validation logic

check-quality/main.go is the script that verifies every linked repository in README.md is alive, has a description, and meets quality thresholds. Like check-pr-diff, it has no companion test file. Because this script runs on a schedule (recheck-open-prs.yaml) and gates merges, an untested bug could silently pass broken links or reject healthy ones. Unit tests with mocked HTTP responses and sample markdown input would make this automation far more reliable.

• [ ] Read .github/scripts/check-quality/main.go to identify all testable units: URL fetching, GitHub API response parsing, markdown link extraction, and quality-threshold logic
• [ ] Refactor inline logic out of main() into package-level functions (e.g. extractLinks(markdown string), checkRepo(client, url) error) to enable unit testing without live network calls
• [ ] Create .github/scripts/check-quality/main_test.go with table-driven tests using httptest.NewServer to mock GitHub API responses for: a valid active repo, a 404 archived repo, a repo with no description, and a rate-limit response
• [ ] Add a test that feeds a small synthetic markdown snippet

Good first issues

1. pkg/slug/generator_test.go likely has limited edge-case coverage — add tests for slugs with Unicode characters, consecutive hyphens, and all-numeric headings. 2. pkg/markdown/convert.go has no test for the full README.md round-trip (parse → HTML → verify anchor links match slug output) — this integration test is missing from convert_test.go. 3. .github/scripts/check-quality/main.go could emit structured JSON error output instead of plain text, making it easier for CI to annotate specific PR lines via GitHub's annotation API.

Top contributors

• @kolkov — 7 commits
• @mike392 — 4 commits
• @rekurt — 3 commits
• @schigh — 3 commits
• @coderfeye13 — 3 commits

Recent commits

• 125412b — Add ubgo/lock to Distributed Systems (#6300) (khanakia)
• 1b51e27 — Add mac-cleanup-go to Other Software section (#6299) (2ykwang)
• 958972c — Add tickstem/heartbeat to Scheduler section (#6298) (mike392)
• 24478f5 — Add tickstem/uptime to DevOps section (#6297) (mike392)
• 5c62bc5 — Add zerohand to DevOps Tools section (#6294) (nilpoona)
• e3c2ebb — Add gogpu/wgpu to Game Development (#6293) (kolkov)
• 9366992 — Add pgxcli to Database Tools section (#6292) (Balaji01-4D)
• f2bcc63 — Add canery to the tools list in README (#6291) (rluders)
• 905824e — Add httpsuite framework to README.md (#6290) (rluders)
• 40eaf53 — Add gogpu/systray to GUI Interaction (#6288) (kolkov)

Security observations

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.