Contributing

Contributing

🌍 English translation is auto-generated on release. See the French version for the current complete page.

Development setup, commit conventions, PR rules (target = develop), i18n requirements, and testing expectations.

Contributing

WorkPilot AI accepts contributions through the standard GitHub flow: fork, branch, implement, and open a pull request. Full guidance on development setup, code style, and testing requirements lives in docs/CONTRIBUTING.md, and the project distinguishes fast local checks from the authoritative CI run.

Local hooks vs. CI

Git hooks are intentionally lightweight, since CI (ci.yml, lint.yml) replays the full suite across Linux, Windows, and macOS on every push to main/develop:

Stage	What runs	Budget
pre-commit	ruff + biome on staged files only, plus tests tied to those files	seconds
pre-push	ruff check, ruff format --check, biome lint	< 30s
CI	pytest, typecheck, vitest, build — on 3 OSes	—

To run the full suite locally before pushing, use PRE_PUSH_FULL=1 git push or pnpm run test:all. Escape hatches exist for troubleshooting (git commit --no-verify, git push --no-verify, PRE_COMMIT_SKIP_TESTS=1), and slow checks can be given more time via PRE_PUSH_TIMEOUT_MS. Contributors should keep ruff pinned to the version CI uses (0.15.7) — a newer version will reformat Python code embedded in markdown files, producing unrelated diffs.

Pull requests and upstream sync

PRs must target the develop branch, never main, which is reserved for releases.

WorkPilot AI tracks the upstream Auto-Claude project. Forks can pull upstream changes with:

pnpm merge-upstream                 # merge upstream/develop and push
pnpm merge-upstream -- --skip-push  # review before publishing
pnpm run validate:upstream          # check the sync tooling is wired up

Platform-specific wrappers live in utils/system/, and .github/workflows/sync-upstream.yml runs the same merge automatically on a schedule.

Getting involved

Bugs and feature requests go through GitHub Issues; broader questions belong in GitHub Discussions. The project is licensed AGPL-3.0 — modifications distributed or run as a service must remain open source under the same license, with commercial licensing available for closed-source use cases.

---

➡️ Continue: Troubleshooting