mirror of
https://github.com/andrewyng/openworker.git
synced 2026-11-20 20:37:44 +00:00
78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# Contributing to OpenWorker
|
|
|
|
Thanks for helping improve OpenWorker. Start with the [README](README.md) for the
|
|
product overview and local development setup. This guide covers the contribution
|
|
workflow.
|
|
|
|
## Pick a change
|
|
|
|
Search [open issues](https://github.com/andrewyng/openworker/issues) and
|
|
[open pull requests](https://github.com/andrewyng/openworker/pulls) 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](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:
|
|
|
|
```bash
|
|
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](https://github.com/andrewyng/openworker/issues/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.
|