Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (57 loc) · 2.48 KB

CONTRIBUTING.md

File metadata and controls

80 lines (57 loc) · 2.48 KB
Raw

Contributing

TaskSignal is a local-first MVP for discovering evidence-backed software opportunities from public discussion data. Contributions should keep the project useful, transparent, and safe to run from a fresh checkout.

Development Setup

  1. Install the locked API and web development dependencies:

    make setup

  2. Run the local setup diagnostic:

    make doctor

  3. Start the API and web app in separate terminals:

    cd apps/api
.venv/bin/uvicorn app.main:app --reload
    cd apps/web
npm run dev

No environment file is required for fixture-backed development. Put optional API overrides in apps/api/.env and web overrides in apps/web/.env.local.

Use make up instead when you want the full Docker Compose stack.

Checks

Run a quick local setup check when starting from a fresh checkout:

make doctor

Run the main checks before opening or merging changes:

make test
make lint

Backend checks live in apps/api and use pytest plus ruff. Frontend checks live in apps/web and use the Next.js build plus Vitest.

Check contributed fixtures before opening a PR:

python3 scripts/check_fixture_redaction.py

Contribution Guidelines

  • Keep fixture mode working without paid services or live API credentials.
  • Keep fixture records synthetic or heavily sanitized. Do not include real usernames, email addresses, API tokens, private/internal URLs, customer data, private repository links, or source payloads from unsupported services.
  • If a fixture needs an author field to exercise hashing behavior, use an obvious placeholder such as contributor-a, edge_hn_user, or backend_dev.
  • Prefer transparent scoring, evidence links, and explainable rules over opaque automation.
  • Do not commit .env files, API keys, exported private datasets, local databases, caches, or build output.
  • Use public APIs and respect source rate limits and terms.
  • Store author hashes rather than raw usernames unless a feature explicitly requires otherwise and documents why.
  • Add or update docs when behavior, setup, deployment, data handling, or model assumptions change.

Pull Request Checklist

  • The change has a clear user or developer benefit.
  • Fixture demo mode still runs locally.
  • Relevant backend and frontend tests pass.
  • Documentation is updated when user-facing behavior or setup changes.
  • No secrets, credentials, local databases, or generated build artifacts are included.