opendesk

Thank you for improving Opendesk. This guide covers local setup, style, tests, and review expectations. Read AGENTS.md for deeper architectural and frontend conventions.

Local setup

Follow the README bench installation first. For frontend work, keep the site running and install the SPA dependencies:

cd apps/opendesk
yarn install
yarn dev

The dev server reads desk/vite.config.js, which proxies Frappe requests and writes production assets to opendesk/public/desk. The backend must remain running for API, authentication, and realtime behavior.

Install the repository's Git hooks once per clone:

pre-commit install
pre-commit run --all-files

Commit conventions

Commits use Conventional Commits as enforced by commitlint.config.mjs. Allowed types are build, chore, ci, docs, feat, fix, perf, refactor, revert, style, and test; types are lower-case and a subject is required. Example:

docs(readme): document the local bench setup

Keep pull requests focused. Branches in this repository target main, main-hotfix, or develop.

Code style

• Python: Black and isort (Black profile) format code; Flake8 checks it. Configuration lives in .pre-commit-config.yaml and .flake8. The pre-commit Flake8 hook runs with .github/helpers/.flake8_strict.
• Frontend: ESLint with Vue 3, TypeScript, Tailwind, and Prettier integrations via .eslintrc.js. Formatting preferences are in .prettierrc.json, and .lintstagedrc configures staged-file ESLint fixes.
• Vue: Prefer the Composition API and <script setup lang="ts">, Tailwind utility classes with semantic tokens, and Lucide icons for new components. See AGENTS.md.

Run the configured hooks before pushing:

pre-commit run --all-files

Tests

Backend behavior changes require tests. Run the full app suite from the bench directory:

bench --site opendesk.localhost run-tests --app opendesk

Place test helpers in opendesk/test_utils.py rather than defining factories inline, and add tests under the existing app test layout.

Browser tests use Playwright against a disposable bench site:

cd apps/opendesk
npx playwright install chromium
BASE_URL=http://localhost:8000 SITE_NAME=opendesk.localhost yarn test:e2e

Every record created by a spec must use a unique name, and site-wide settings changed by a spec must be restored. See e2e/README.md for the persona and fixture model.

Documentation

When a feature has a specification document, the spec is its living source of truth. Update it in the same change that alters behavior: add new APIs, components, and decisions, and remove sections for removed behavior. Do not defer spec updates.

Pull request checklist

• The change is scoped to one problem and its description explains the behavior change.
• Commit titles follow Conventional Commits.
• Pre-commit hooks and the relevant linters pass locally.
• Backend changes include tests, and the app test suite passes for affected areas.
• UI changes include or update Playwright coverage where a user journey is affected.
• Affected specifications and user-facing documentation are updated.
• No unrelated files, generated assets, or reformatting are included.