Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
128 lines (91 loc) · 5.11 KB

CONTRIBUTING.md

File metadata and controls

128 lines (91 loc) · 5.11 KB

Contributing to JobOps

Thanks for helping improve JobOps.

This guide is intentionally short and GitHub-friendly. It focuses on contributor workflow and links to the existing docs for setup, style, and troubleshooting so we do not duplicate documentation.

What You Can Contribute

  • Bug fixes and reliability improvements
  • UI/UX improvements
  • Extractors and integrations
  • Documentation updates
  • Tests and developer experience improvements

Before You Start (Pick a Path)

Use the path that matches your change:

Path Main folders Start command(s) Canonical docs
Docs/content docs-site/docs npm run docs:dev Docs style guide, FAQ
App/UI/API orchestrator, shared npm --workspace orchestrator run dev Self-hosting, Troubleshooting
Extractors extractors/*, sometimes shared Relevant type checks + tests Add an extractor, Extractors overview

Local Setup (Minimal)

For full end-user setup, environment variables, OAuth, and deployment details, use the Self-Hosting Guide and Gmail OAuth Setup.

Contributor baseline from repo root:

npm ci
npm --workspace orchestrator run db:migrate
npm --workspace orchestrator run dev

If you are working with extractors that use Glassdoor, Indeed, or LinkedIn (powered by python-jobspy), set up the Python venv once:

python3 -m venv extractors/jobspy/.venv
extractors/jobspy/.venv/bin/pip install -r extractors/jobspy/requirements.txt

The runner auto-detects the venv — no need to set PYTHON_PATH.

If you are editing docs:

npm run docs:dev

Local URLs:

  • Orchestrator UI: http://localhost:5173
  • Orchestrator API: http://localhost:3001
  • Docs site: http://localhost:3006

How to Make a Change

  1. Create a branch from origin/main.
  2. Keep the PR focused on one change or one problem.
  3. If the change is user-visible, update docs (or link the relevant docs update in the same PR).
  4. Include screenshots or short clips for UI changes when helpful.
  5. Mention any tradeoffs or follow-up work in the PR description.

Releases

Releases are driven from GitHub Actions.

  1. Open the release workflow in GitHub Actions.
  2. Enter the next version as x.y.z (for example 0.1.30).
  3. Optionally enter a separate release title for GitHub (for example Google Dorks!).
  4. Run the workflow.

The workflow will:

  • bump orchestrator/package.json
  • update package-lock.json
  • cut the matching Docusaurus docs version
  • commit the version bump to main
  • create and push tag vX.Y.Z
  • publish the ghcr.io/.../job-ops image for that release
  • create the GitHub release using either the custom title or vX.Y.Z

The app version shown in the UI is sourced from orchestrator/package.json, so the release version, tag, and displayed app version stay aligned even when the GitHub release title is customized separately.

Validation Before PR (CI-Parity Checks)

Run from the repository root:

./orchestrator/node_modules/.bin/biome ci .
npm run check:types:shared
npm --workspace orchestrator run check:types
npm --workspace gradcracker-extractor run check:types
npm --workspace ukvisajobs-extractor run check:types
npm --workspace orchestrator run build:client
npm --workspace orchestrator run test:run

If tests fail due to a better-sqlite3 Node ABI mismatch, rebuild it and rerun tests:

npm --workspace orchestrator rebuild better-sqlite3

CI runs on Node 22. If local behavior differs, verify with Node 22 before concluding a change is valid.

Project-Specific Standards (Link-First)

Before editing server routes/services, read AGENTS.md for repository standards, especially:

  • /api/* response contract and status/code mapping
  • Correlation/request IDs (x-request-id) and logging context
  • Shared logger usage in core server paths (no direct console.*)
  • SSE helper usage
  • Redaction/sanitization defaults for logs and error details
  • Minimal webhook and LLM payload defaults

Where to Find Deeper Docs