Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
69 lines (48 loc) · 2.66 KB

CONTRIBUTING.md

File metadata and controls

69 lines (48 loc) · 2.66 KB
Raw

Contributing to AEO Radar

Thanks for considering a contribution. This document covers the basics. For architecture and day-to-day development, see CLAUDE.md.

Ways to contribute

  • Report a bug — open an issue with a reproduction (crawl logs, screenshots, package.json / OS versions).
  • Suggest a feature — open a GitHub Discussion first so we can scope it before code is written.
  • Add an engine — subclass BaseCrawler (see "Adding a platform" in README.md).
  • Improve the dashboard — the grayscale theme is intentional; design PRs should preserve it.
  • Fix typos / docs — always welcome.

Dev setup

git clone https://github.com/hellowalt/aeo-radar.git
cd aeo-radar
nvm use              # uses .nvmrc (Node 20)
npm install
cd web && npm install && cd ..
npx playwright install chromium
npm run db:push

Edit src/config/brand.ts with a throwaway brand before running npm run seed / npm run crawl.

Before you open a PR

  1. npx tsc --noEmit passes (root).
  2. cd web && npx tsc --noEmit passes.
  3. cd web && npm run build succeeds.
  4. Your change doesn't add hardcoded brand names, keywords, or domain-specific copy. Everything brand-specific lives in src/config/brand.ts.
  5. No commits to data/, auth/, .env, or any profile directory.

Commit messages

Use Conventional Commits:

feat: add gemini crawler
fix: handle stop-button absent on ChatGPT o1 models
doc: clarify macOS TCC gotcha in 0002

Types we accept: feat, fix, doc, refactor, perf, test, build, ci.

Adding a new platform

This is the most common contribution. A good PR:

  1. Implements a subclass of BaseCrawler in src/crawlers/<name>.ts.
  2. Adds the name to LLM_PLATFORMS in src/types.ts and a case to createCrawler() in src/pipeline/runner.ts.
  3. Adds an entry to PLATFORM_COLORS in web/src/lib/theme.ts (grayscale).
  4. Includes a selector-stability note in the PR body: which DOM selectors you used, how you confirmed they're stable, how a reader should re-verify if the engine ships a UI change.
  5. Documents any workarounds (e.g. launchChannel: 'chrome') with a comment pointing to the decision doc or the symptom you fixed.

Code style

  • TypeScript strict mode.
  • No mass-reformat PRs — keep diffs minimal and scoped.
  • Comments: only when they explain why. The code already tells the reader what.

Code of Conduct

Be kind. We follow the Contributor Covenant v2.1.

License

By contributing you agree that your contributions will be licensed under the MIT License.