Contributing

Workflow

Open a PR against main; CI runs the full matrix (see CI/CD).
Keep changes focused. Match the style of the surrounding code and the conventions below.
Add tests for new behavior in the matching suite.

Python conventions (`services/`)

Follow the existing package layout under src/ (e.g. scoring/, domain_intel/, social/, ai/).
Use structured logging events with extra={...} rather than ad-hoc strings.
Keep async work in the orchestrator patterns already established (stage/pipeline abstractions).
New tests go in services/tests/; keep them hermetic — mock external APIs (see the stub_dnstwist fixture) unless the test is explicitly an integration probe.

Rails conventions (`rails_web/`)

New platform settings are PlatformSetting keys, not schema changes, where possible.
JSON documents (findings, profiles, scoring traces) live in jsonb columns — additive fields don’t require migrations.
Controller tests use SessionTestHelper#sign_in_as.

AI features

AI is always a best-effort enhancement:

Never block a scan, report, or takedown on a model call — provide the deterministic fallback.
Log structured skip/failure events (ai_audit_skipped_not_enabled, report_ai_deterministic_fallback, …).
Configuration flows through the admin ai_provider setting; env vars are fallbacks only.

Quality gates

Check	Command
Python tests	`cd services && .venv/bin/pytest -q`
Rails tests	`cd rails_web && bin/rails test`
RuboCop	`bundle exec rubocop` (rubocop-rails-omakase)
Brakeman	`bundle exec brakeman`
bundler-audit	`bundle exec bundler-audit check`
importmap audit	`bin/importmap audit`

Documentation

Docs live in docs/ (Starlight). To add a page:

Create a .mdx file under src/content/docs/<section>/.
Add it to the sidebar in astro.config.mjs.
Preview with astro dev --background, and verify with npm run build.

The docs/AGENTS.md file records the background-mode dev-server convention for AI agents.

See also