Contributing

OpenOpps changes should keep the CLI, web app, generated artifacts, OpenSpec, and validation recipes aligned. The project is pre-release, but the local workflow should still be reproducible and reviewable.

Package vs URL: The Next/Fumadocs package lives under web/ in the repository. Public docs routes stay under /docs/* (for example /docs/contributing).

Local Setup

uv sync
just --list
uv run openopps --help
cd web && pnpm install

Use uv run openopps ... inside the repository checkout. Install the editable tool only when you want the openopps command available directly:

uv tool install -e .
openopps status

Validation

Use just from the repository root for local parity with GitHub Actions. Prefer the canonical web-* recipes; transitional docs-* aliases invoke the same web-* recipes.

just quick
just ci
just lock-check
just openspec-validate-all
just web-check
just web-test
just cli-help

The underlying commands remain direct and scriptable:

uv run pytest
uv run pytest --cov=openopps --cov-report=term-missing
uv lock --check
rtk npx -y @fission-ai/openspec@1.6.0 validate --all --strict
cd web && pnpm types:check
cd web && pnpm build
cd web && pnpm lint
cd web && pnpm test
just web-search-index-check

just ci composes the ci-python, ci-openspec, ci-web, and ci-artifacts lanes; just ci-full adds network-dependent security audits and lowest-direct dependency testing. just web-rtk-lint is the explicit optional maintainer lint for rtk and is not part of the default CI recipe. GitHub Actions adds the supported Python matrix, dependency review, and a non-PR wheel/SBOM attestation job. The current supply-chain job attests the Python wheel only, not a v7 public-data recovery archive.

Web App Workflow

Docs content lives in web/content/docs/*.mdx, and navigation order lives in web/content/docs/meta.json.

cd web
pnpm data:generate
pnpm types:check
pnpm build
pnpm lint
pnpm test

pnpm data:generate refreshes package-derived source/provider/export metadata. pnpm types:check also regenerates that metadata before Fumadocs MDX artifacts, Next.js route types, and TypeScript checks. Use just web-build from the repository root for production web build assurance; it also runs the API function trace check.

The static jobs/explorer index is separate because regeneration requires a clean local public kaggle/openoppsdb.sqlite snapshot (ignored by git). Recipes fail loud if that file is missing:

just web-search-index
just web-search-index-check

CI never opens SQLite. It validates the committed v6 transition artifact graph with just web-search-artifacts-check and the schema check inside just web-check (pytest -k committed). Run just web-search-index-check only when intentionally regenerating web/public/data/openopps-search/ from a clean local snapshot.

Version 7 generation writes to a separate publication root and is fail-closed on freshness, source rights, required attribution, privacy, exact closure, provenance, and platform budgets:

uv run python scripts/generate_docs_search_index.py \
  --data-db kaggle/openoppsdb.sqlite \
  --release-root /absolute/path/to/openopps-search-v7 \
  --channel production \
  --max-snapshot-age-hours 48
uv run python scripts/verify_docs_search_artifacts.py \
  --root /absolute/path/to/openopps-search-v7 \
  --channel production \
  --max-snapshot-age-hours 48
uv run python scripts/docs_search_delivery.py \
  validate-config deployment/openopps-data

See Public Data Releases before changing artifact schema, rights metadata, public-data environment variables, the shared snapshot client, search worker, assets-only configs, archive contents, or v6 compatibility. Live upload/deploy, GitHub Release publication, v6 removal, and Git history rewriting are separate authority boundaries; a local green run does not authorize or prove them.

Public Workflow Changes

Use OpenSpec for non-trivial changes to public workflows, generated asset formats, downstream agent tooling, docs generation, or validation behavior. Pin @fission-ai/openspec@1.6.0 in copy-paste commands (not @latest); set OPENOPPS_OPENSPEC to align just openspec-* with the same pin.

rtk npx -y @fission-ai/openspec@1.6.0 list --json
rtk npx -y @fission-ai/openspec@1.6.0 validate --all --strict

When commands, workflows, or generated surfaces change, update the relevant MDX page, root README, nested AGENTS.md, Justfile, CI workflow, and OpenSpec change in the same logical workstream.

Source and Provider Changes

Source adapters discover candidate company boards. Provider adapters detect or fetch postings from public job-board providers.

• Keep source adapters low-side-effect and explicit about upstream access.
• Preserve source provenance in durable board records.
• Keep route probing dry-run-first; persist with --apply only after matched routes are reviewed.
• Add semantic tests for provider support and normalized output.
• Use providers coverage, providers audit, and admin sources yield to evaluate persisted coverage before changing public claims.

Installed Python plugins are not sandboxed and run in the same process as OpenOpps. Use OPENOPPS_PLUGIN_ALLOWED for trusted plugin entry points and OPENOPPS_PLUGIN_AUTOLOAD=true only in controlled environments.

Data and Telemetry Contributions

Export and static-index changes must keep the data contract clear:

• Update Data Model when entities, export formats, search-index fields, facets, suggestions, or telemetry events change.
• Prefer generated counts and generated manifests over copied prose counts.
• Keep SQLite, CSV, Parquet, and JSONL export semantics aligned.
• Keep telemetry first-party, env-gated, size-capped, and sanitized.
• Treat the local event lake as the canonical telemetry sink; optional dashboards or hosted adapters are mirrors.
• Keep packaged source rights canonical for packaged sources. Missing or needs_review rights states fail v7 publication; required attribution must be present in the generated policy report.
• Never hand-edit an immutable v7 release, channel pointer, policy report, or recovery archive. Correct the source of truth and regenerate.

Secret Hygiene

Keep credentials local. .env, .env.*, .envrc, Kaggle kaggle.json, local package-registry credential files, .netrc, key bundles, and token or credential JSON files are ignored; .env.example remains the tracked non-secret template.

Do not print credentials in logs, docs, CI output, generated artifacts, or screenshots. Live Kaggle publishing remains a maintainer-only local action and is intentionally outside CI.