Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
89 lines (61 loc) · 3.47 KB

CONTRIBUTING.md

File metadata and controls

89 lines (61 loc) · 3.47 KB
Raw

Contributing to ai-bot-shield

Thanks for considering a contribution. This project lives or dies on community participation — adding a new AI bot signature takes about three minutes, and it directly helps every other site running this middleware.

Add a signature in 3 minutes

The fastest contribution path is to flag an AI bot we don't yet know about.

  1. Open a new-signature issue.
  2. Fill in the structured form (operator name, user-agent regex, recommended action, evidence URL).
  3. A maintainer reviews within 7 days and either lands a PR adding it to signatures/registry.json, asks for more evidence, or closes with a reason.

Evidence is non-negotiable. We require at least one of: (a) the operator's public documentation; (b) a captured server log showing the user-agent; (c) a third-party verified-bot list (Cloudflare Radar, Imperva, ai.robots.txt). This prevents griefing — without evidence, someone could add ^.*$ and break the world.

Code contributions

Setup

# Install Mise to manage tool versions
curl https://mise.run | sh

# Clone and bootstrap
git clone https://github.com/mthamil107/ai-bot-shield.git
cd ai-bot-shield
mise install   # installs Node 22, Python 3.12, Go 1.23, pnpm, uv

# Per-language setup
cd packages/node    && pnpm install         && cd ../..
cd packages/python  && uv sync              && cd ../..
cd packages/go      && go mod download      && cd ../..

Running tests

# Run everything locally
cd packages/node    && pnpm test            && cd ../..
cd packages/python  && uv run pytest        && cd ../..
cd packages/go      && go test ./...        && cd ../..

# Parity check — the SAME 200 requests through all three middlewares.
# Verifies that Node / Python / Go produce identical decisions.
python tests/parity/run_parity.py

The parity test is load-bearing. If you touch any detector logic, run it.

What we want

  • New framework adapters (Django, Rails, Hapi, Fastify, chi, gin, echo extensions)
  • More real-bot fixtures in tests/fixtures/real-bot-requests/
  • Documentation improvements per framework guide
  • Performance improvements (target: p99 < 0.5ms per request)
  • RFC 9421 verification module robustness (week-2 work)

What we don't want

  • New detection heuristics without an associated test fixture
  • Dependencies on heavy ML or remote APIs
  • TLS termination, proof-of-work challenges, or CAPTCHAs (we delegate those — Anubis handles PoW, Cloudflare handles TLS)
  • Telemetry that phones home

Pull request flow

  1. Fork, create a feature branch.
  2. Make the change. Add a test (real or fixture-based).
  3. Run the parity check if you touched detector logic.
  4. Open a PR. The title should be in imperative ("Add Bytespider IP-range matching"), not past tense.
  5. CI runs Node / Python / Go suites. Green CI is required to merge.
  6. A maintainer reviews. Expect feedback; don't be discouraged if changes are requested.

Code style

  • Node: TypeScript strict mode, formatted with Biome.
  • Python: PEP 8, formatted with Ruff. mypy --strict clean.
  • Go: standard gofmt, golangci-lint clean.

Security disclosure

See SECURITY.md. Do not open public issues for security bugs.

Code of conduct

See CODE_OF_CONDUCT.md. The short version: be kind, assume good intent, focus on the work.

Maintainers

See GOVERNANCE.md for the maintainer list and decision-making process.