Skip to content

Development and Contributing

Jump to bottom
Chris Nighswonger edited this page Mar 26, 2026 · 3 revisions

Development and Contributing

This page describes practical local development workflows for Kanfei. For the full contributor guide — including code quality standards, PR process, and AI-assisted contribution policy — see CONTRIBUTING.md in the repo.

Repo Layout

  • backend/ FastAPI app + logger daemon + protocol/services/models
  • frontend/ React + TypeScript + Vite app
  • tests/backend/ backend test suite
  • tests/e2e/ Playwright end-to-end test suite
  • scripts/ hooks and tooling (pre-push hook, E2E report generator)
  • reference/ Davis protocol reference materials

Local Setup

python station.py setup

Run Modes

Production-style app server:

python station.py run

Development mode (backend + frontend dev server):

python station.py dev

Testing

Backend tests:

python station.py test

Frontend type check:

cd frontend && npx tsc --noEmit

Both must pass before submitting changes.

E2E Tests (Playwright)

E2E tests run locally, not in CI. They are required for UI behavior changes — dashboard rendering, gauge layout, Settings UI, navigation, WebSocket/data pipeline changes, and API shape changes. They are not required for backend-only changes, pure CSS tweaks, documentation, CI config, or driver additions.

Setup (one-time):

cd frontend && npm run build
cd ../tests/e2e && npm install
npx playwright install chromium

Run and generate a markdown report for your PR:

./scripts/e2e-report.sh

The report script runs all Playwright specs against a fixture database on port 8765 (avoids conflicts with a running station.py run on 8000) and outputs a markdown summary with pass/fail counts, duration, and failure details. Paste the output into your PR comment before requesting review.

Pre-push hook

The repo includes a pre-push hook that reminds you to run the E2E suite when pushing an E2E branch. Install it with:

git config core.hooksPath scripts/hooks

The hook is informational only — it does not block the push.

Configuration for Dev

  • Defaults come from .env.example.
  • Active runtime config is persisted in SQLite station_config.
  • Setup Wizard can initialize config if DB is empty.

Hardware Development Notes

  • Logger daemon is the only process that should own the station connection (serial device or network socket).
  • Use setup probe/auto-detect endpoints for safe detection workflows.
  • If hardware is absent, degraded mode still allows UI and many APIs for frontend work.

Adding a New Hardware Driver

See Driver Development for the full guide covering the StationDriver interface, SensorSnapshot field reference, driver registration, and test fixture workflow.

Branching / Git Workflow

  • main is the primary development and release branch
  • feature/* branches for larger work, fix/* for bugfixes
  • feature/e2e/* or fix/e2e/* for changes that require E2E testing (UI behavior changes)
  • PR flow into main
  • Small changes can go directly to main; larger work should use branches + PRs
  • Multi-phase issues: use Ref #N (not Closes #N) until the final phase PR
  • E2E branches: run ./scripts/e2e-report.sh and post results to PR before requesting review

AI-Assisted Contributions

AI tools (Claude Code, Copilot, Cursor, etc.) are welcome. The project evaluates contributions on quality, not origin. Key requirements:

  • Disclose AI use in the PR description (a simple "AI-assisted" is fine)
  • Understand every line — you must be able to explain your code when asked
  • Verify, don't trust — check that imports exist, function signatures are correct, and the code actually runs
  • Run all tests, not just the ones you wrote
  • No bulk AI refactors without prior discussion in an issue

See CONTRIBUTING.md for the full AI policy, including what reviewers look for and what will get a PR rejected.

Proprietary Components

The kanfei-nowcast package is a separate proprietary product. Do not reference its internal architecture, detection algorithms, or implementation details in issues, PRs, or code comments. Describe only user-visible symptoms and outcomes.

Documentation Contributions

When adding docs:

  • prefer file/module references
  • avoid describing features not present in code
  • update related wiki pages when adding endpoints/config keys
  • verify documentation against actual code behavior — do not document what code should do

Suggested Contribution Areas

  • hardware driver testing (see Supported Hardware for in-testing drivers)
  • API response examples in wiki pages
  • additional troubleshooting playbooks
  • integration testing for IPC and service interactions
  • documentation for deployment hardening (reverse proxy, backup automation)

Reporting Bugs and Feature Requests

Related Pages

Clone this wiki locally