From b00fb4fba1bd8334ce310d4a24e87f4ff4e90ba6 Mon Sep 17 00:00:00 2001 From: DaKheera47 Date: Sun, 22 Feb 2026 21:16:20 +0000 Subject: [PATCH] contributing.md --- CONTRIBUTING.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 +++ 2 files changed, 104 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3ccbc7b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,98 @@ +# 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](https://jobops.dakheera47.com/docs/next/reference/documentation-style-guide), [FAQ](https://jobops.dakheera47.com/docs/next/reference/faq) | +| App/UI/API | `orchestrator`, `shared` | `npm --workspace orchestrator run dev` | [Self-hosting](https://jobops.dakheera47.com/docs/getting-started/self-hosting), [Troubleshooting](https://jobops.dakheera47.com/docs/next/troubleshooting/common-problems) | +| Extractors | `extractors/*`, sometimes `shared` | Relevant type checks + tests | [Add an extractor](https://jobops.dakheera47.com/docs/next/workflows/add-an-extractor), [Extractors overview](https://jobops.dakheera47.com/docs/extractors/overview) | + +## Local Setup (Minimal) + +For full end-user setup, environment variables, OAuth, and deployment details, use the [Self-Hosting Guide](https://jobops.dakheera47.com/docs/getting-started/self-hosting) and [Gmail OAuth Setup](https://jobops.dakheera47.com/docs/getting-started/gmail-oauth-setup). + +Contributor baseline from repo root: + +```bash +npm ci +npm --workspace orchestrator run db:migrate +npm --workspace orchestrator run dev +``` + +If you are editing docs: + +```bash +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. + +## Validation Before PR (CI-Parity Checks) + +Run from the repository root: + +```bash +./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: + +```bash +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`](./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 + +- [Documentation Home](https://jobops.dakheera47.com/docs/) +- [Self-Hosting Guide](https://jobops.dakheera47.com/docs/getting-started/self-hosting) +- [Gmail OAuth Setup](https://jobops.dakheera47.com/docs/getting-started/gmail-oauth-setup) +- [Documentation Style Guide](https://jobops.dakheera47.com/docs/next/reference/documentation-style-guide) +- [FAQ (includes where to edit docs)](https://jobops.dakheera47.com/docs/next/reference/faq) +- [Add an Extractor Workflow](https://jobops.dakheera47.com/docs/next/workflows/add-an-extractor) +- [Troubleshooting](https://jobops.dakheera47.com/docs/next/troubleshooting/common-problems) diff --git a/README.md b/README.md index 024db58..54204e5 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,12 @@ If you want the serious view of the project, start here: - [Extractor System](https://jobops.dakheera47.com/docs/extractors/overview) - [Troubleshooting](https://jobops.dakheera47.com/docs/troubleshooting/common-problems) +## Contributing + +Want to contribute code, docs, or extractors? Start with [`CONTRIBUTING.md`](./CONTRIBUTING.md). + +That guide is intentionally link-first so contributor workflow lives in one place while setup and feature docs stay in the canonical docs site. + ## Quick Start (10 Min) Prefer guided setup? Follow the [Self-Hosting Guide](https://jobops.dakheera47.com/docs/getting-started/self-hosting).