Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
64 lines (42 loc) · 3.04 KB

CONTRIBUTING.md

File metadata and controls

64 lines (42 loc) · 3.04 KB
Raw

Contributing to Satellite Eye

Thank you for your interest in contributing.

Development workflow

  • Follow the Quick start section in README.md to run the API and frontend.
  • Before submitting changes, run make check-full (or make check for backend-only edits).
  • For critical flows (routing, intent handling, channel resolution), follow docs/critical-flow-test-checklist.md.

Quality commands

make check          # Backend: types, rules, standards, critical tests
make check-full     # Backend + frontend: lint, types, all tests
make stop           # Stop background dev processes
  • Install pre-commit hooks once per clone: pip install pre-commit && pre-commit install.
  • CI runs the same commands via .github/workflows/quality-gate.yml.

Quality gate

  • Target zero errors, zero warnings, and zero informational diagnostics in the scope you edit.
  • Use make check-full to align with CI before opening a PR.

Language and naming

  • Use English for identifiers, comments, commit messages, and technical documentation.
  • User-facing copy in the web UI defaults to English unless the feature explicitly targets another locale.

Prompts and LLM-related code

  • Keep prompts generic and language-agnostic; do not hardcode a specific culture, person, or region.
  • Centralize prompt text in the PromptRegistry; do not scatter prompts across unrelated files.

Code quality

  • Remove unused fields, methods, imports, and dead code in files you touch.
  • Prefer DRY abstractions over copy-pasted logic; follow SOLID for new and refactored code.
  • Keep domain logic free of provider-specific assumptions (LLM, STT, vision) — use adapters or configuration.
  • Avoid hardcoded rules tied to a specific broadcaster, brand, or domain; prefer configuration-driven behavior.
  • Prefer structured, validated outputs (e.g. JSON) for LLM/vision integration over unconstrained free text.
  • Do not add ad-hoc loggers or noisy logging; use clear returns and exceptions for error handling.

Architecture

  • Keep layers replaceable (storage, providers, transports); core behavior should not depend on a single vendor or model.
  • Long-running work should be async or offloaded so request threads are not blocked.
  • External tools (e.g. ffmpeg) should be invoked through shared helpers, not one-off shell strings.

Testing

  • Changes that affect routing, intent handling, channel resolution, or Telegram/API behavior must include regression tests that mirror real user flows — not only helper unit tests.
  • Run the relevant tests before considering a change done.

Git commits

  • Write commit messages in English, imperative mood (e.g. "Add docs router", "Fix channel disambiguation").
  • Prefer logical, scoped commits (e.g. backend, frontend, docs separately) over one large unrelated commit.

Out of scope for drive-by refactors

  • Do not refactor generated or third-party trees (node_modules, frontend/dist, lockfiles) unless the task explicitly requires it.