Skip to main content

Contributing

This page mirrors the repository .github/CONTRIBUTING.md.

Scope and Principles​

  • Open an issue before large work.
  • Prefer small, focused pull requests.
  • Keep API contracts and DB schema changes explicit.
  • Do not mix unrelated refactors with feature/bug fixes.

Repository Layout​

  • web/: SvelteKit API + dashboard
  • orchestrator/: queue scheduler / tool runner
  • Tool runtimes: probe/, domain/, whois/, ssl/, seo/, wcag/, security/, stress/, mail/
  • Shared contracts: types.d.ts, constants.ts
  • DB schema: web/src/lib/server/schema.surql
  • Docs: docs/

Requirements​

  1. Linux, macOS, or WSL UNTESTED
  2. Docker with compose
  3. Node.js ^22.22.1
  4. Bun ^1.3.10
  5. pnpm

Local Setup​

  1. Clone:
git clone https://github.com/rallisf1/hesperida.git
cd hesperida
  1. Configure env:
cp .env.example .env
ln -s .env web/.env
  1. Build tool dependencies

the main branch is for development because it is synced with the original upstream repos, use the hesperida-* branch if you have errors

cd mail
git clone https://github.com/rallisf1/wraps.git wraps
cd wraps
pnpm install --frozen-lockfile
pnpm --filter @wraps/core build
pnpm --filter @wraps/email-check build

cd ../seo
git clone https://github.com/rallisf1/seo-audit-skill.git seomator
cd seomator
npm install && npm run build
  1. Build tools:
docker compose -f docker-compose.dev.yaml --profile tools build
  1. Start infra:
docker compose -f docker-compose.dev.yaml --profile dev up
  1. Run web app:
cd web
bun install
bun run dev

Environment Notes​

  • SURREAL_* must point to a reachable DB.
  • System email routes (forgot, invite, transfer ownership, admin user create) require SMTP (SMTP_*).
  • Use NODE_ENV=development.
  • Apprise is used for user notification targets, not for system mail.

Branch and PR Workflow​

  1. Create a feature branch from main.
  2. Make changes with clear commit messages.
  3. Run checks/tests locally (see below).
  4. Update docs/changelog when behavior changes.
  5. Open PR to development with:
    • what changed
    • why
    • migration/ops impact
    • test evidence

Testing Requirements​

Web typecheck​

cd web
bun run check

Web tests​

cd web
bun run test

Tool runs​

Create a Job with all available tools and check that they all succeed.

Notes:

  • Integration tests need reachable SurrealDB.
  • web/src/tests/helpers/preload.ts sets test defaults.

API and Schema Change Rules​

If you change API behavior:

  • Update route @swagger docs in web/src/routes/api/v1/**/+server.ts.
  • Regenerate and commit web/static/openapi.json (build web once).
  • If dashboard consumes that API, update dashboard loaders/mappers accordingly.

If you change schema/ACL:

  • Update web/src/lib/server/schema.surql.
  • When updating existing fields, make sure they use OVERWRITE instead of IF NOT EXISTS.
  • Increase the version in web/package.json.
  • Verify startup DB init still succeeds (web/src/lib/server/db-init.ts).
  • Add/adjust tests for permission behavior and regressions.

Notification Rules​

  • System mail goes through web/src/lib/server/system-mail.ts (Nodemailer).
  • User notification target test/send stays in Apprise modules under web/src/lib/server/notifications/.
  • Preserve rollback semantics for routes that create temporary tokens/users when email fails.

Docs Workflow​

Docs are built from docs/ with Docusaurus.

cd docs
npm ci
npm run build

docs build scripts sync OpenAPI from web/static/openapi.json, so keep that file current in PRs that touch API contracts.

CI/CD and Release Expectations​

  • docs-pages.yml: builds and deploys docs from main.
  • auto-tag-version.yml: creates tag v<web/package.json version> when that version changes on main.
  • images-ghcr.yml: builds/pushes multi-arch images on tag pushes.

Version source of truth is web/package.json.

If you bump version:

  • Add matching CHANGELOG.md section.
  • Ensure API/docs updates are committed before merge.

AI Coding Usage​

AI Coding is expected at this point. Over 90% of the project's code has been AI generated at this point. Just make sure you know what the AI is doing. Use ARCHITECTURE.md to give your agent a head start. Models recommended:

  • GPT-5.3-Codex
  • Gemini 3.1 Pro

PR Checklist​

  • Change is scoped and reviewed for side effects.
  • bun run check passes in web/.
  • Relevant tests pass locally.
  • Schema/API/docs updated as needed.
  • CHANGELOG.md updated for user-visible behavior.
  • New env vars are documented in .env.example and docs config reference.

Security and Sensitive Changes​

  • Never commit secrets in .env, workflow files, or tests.
  • For auth/ACL changes, include explicit tests for allowed/forbidden paths.
  • For destructive operations (delete/transfer), preserve current safeguards and rollback behavior.