openworker/CONTRIBUTING.md

Contributing to OpenWorker

Thanks for helping improve OpenWorker. Start with the README for the product overview and local development setup. This guide covers the contribution workflow.

Pick a change

Search open issues and open pull requests before starting. Check the issue discussion and the PR list for the issue number or relevant code path so you do not duplicate active work. For a new feature or a large behavior change, discuss the direction in an issue first: the project has an active internal roadmap. For security vulnerabilities, follow SECURITY.md and report privately.

Prefer a focused PR with a reproduction, the smallest useful fix, and a regression test. Keep unrelated cleanup on a separate branch.

Prepare your fork

Python 3.10 or newer and Node.js 20 are required by the project metadata and CI. The bootstrap script picks the newest Python 3.10+ on your PATH (it tries python3.14 down to python3) and prints which one it chose; if none qualifies it lists what it checked and exits, so install a newer Python (macOS: brew install python@3.13) and rerun. For desktop development, install the platform prerequisites for Tauri 2; the browser UI and Python tests do not need a packaged desktop app.

Fork the repository on GitHub, then run:

git clone https://github.com/<your-user>/openworker.git
cd openworker
git remote add upstream https://github.com/andrewyng/openworker.git
git fetch upstream
git switch -c fix/short-description upstream/main
bash packaging/setup_dev_env.sh

On Windows, use WSL for this bootstrap flow. Git Bash currently creates a .venv/Scripts/ layout that the script does not handle (see #9). The README shows how to start the server and browser UI; from surfaces/gui/, run npm ci before GUI tests or development.

Validate the change

Run the narrow checks while iterating, then the relevant full checks before opening a PR:

Changed area	Focused check	Full check
Python backend	.venv/bin/pytest tests/test_relevant_area.py -q	.venv/bin/pytest tests -q --cov=coworker --cov-report=term-missing
GUI logic	cd surfaces/gui && npm test -- path/to/relevant.test.tsx	cd surfaces/gui && npx tsc --noEmit && npm test
GUI workflow	cd surfaces/gui && npx playwright test e2e/relevant.spec.ts	cd surfaces/gui && npx playwright install chromium && npm run e2e

CI uses Python 3.12, Node 20, and the hermetic Playwright suite; it installs .[messaging,dev,bedrock] for the Python job. In a manually created Windows virtual environment, run Python tests with .venv/Scripts/python.exe -m pytest. If you cannot run a check locally, say so in the PR and include the checks you did run.

Open a pull request

1. Rebase or merge the latest upstream/main into your branch and resolve any conflicts.
2. Commit the focused change and push your branch to your fork.
3. Open a PR targeting andrewyng/openworker:main. Link the issue and explain the failure, fix, and validation.
4. Attach before/after screenshots for visible UI bugs and changes, as requested in the README. For nonvisual changes, include a short reproduction and test output, and explain why a screenshot is not applicable.
5. Watch CI and review feedback; update the same branch with corrections.

A first-time fork's GitHub Actions run may require maintainer approval. Do not interpret an unstarted workflow as a passing test.