Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
116 lines (85 loc) · 4.95 KB

CONTRIBUTING.md

File metadata and controls

116 lines (85 loc) · 4.95 KB
Raw

Contributing

Thanks for helping improve TaskTime Pro.

TaskTime Pro is a production local-first app. Contributions should keep the app reliable for existing users and easy for new developers to understand.

Before You Start

  • Keep changes focused and easy to review.
  • Prefer existing patterns in src/hooks/, src/stores/yjs/, src/agent/, and the UI components.
  • Do not add new dependencies unless the benefit is clear.
  • Do not commit secrets, provider account IDs, private worker code, deployment workflows, or internal runbooks.
  • Report security issues through the process in SECURITY.md, not public issues.
  • Follow CODE_OF_CONDUCT.md in issues, pull requests, discussions, package listings, and other project spaces.
  • Follow PRIVACY.md when sharing logs, screenshots, examples, agent outputs, or bug reports.

Development

All Node/npm commands run through Docker.

make install
make dev
make lint
make typecheck
make test-run
make build

An operator checkout with the private infrastructure repository uses make dev for the complete local Worker and Stripe test-mode stack. The optional site joins the same tasktime Docker Desktop group on port 3102, beside the app on 3101. Stop/Play controls the prepared group; make stop preserves containers, and make logs follows their detached output. Tooling uses tasktime-tools separately. The public repository continues to start the core app (and site when present) when the private checkout is absent; use make dev-core when you deliberately need that isolated path.

Use make npm CMD="<command>" for arbitrary npm commands. Do not run npm directly on the host.

Core builds only dist-app (app shell, PWA, public-route redirects, SPA fallback, and non-indexable robots). Public pages live in an independent, ignored tasktime-site/ checkout with its own Docker commands, CI, and dist output. Use make site-dev to start its grouped service, or make site-build / make site-test for independent validation. Core builds never need it. Run make npm CMD="run test:build-artifacts" for core artifact/redirect and documentation-export checks. Site owns its page, link, canonical, discovery, and responsive browser tests.

See the distribution contract before changing shared public metadata. Copy-only site changes need no app release. Changes in the nested repositories must be reviewed and committed separately; core Git intentionally does not track them. Do not add a gitlink or force-add them.

Pull Requests

Good pull requests usually include:

  • A clear description of the user-facing or developer-facing change
  • Tests for behavior changes, especially persisted data, sync, invoices, expenses, timers, reports, and agent commands
  • Notes about compatibility or migration impact when stored data is involved
  • Updated public docs when commands, packages, agent tools, or workflows change

Before requesting review, run the smallest useful verification set. For broad changes, run:

make lint
make typecheck
make test-run
make build

Use Playwright smoke tests for browser flows:

make test-e2e-smoke

The smoke gate includes billing-enabled Reports navigation after a shared-modal Vite hot update, using its own server and disposable browser data. Fresh page loads alone do not exercise this lazy-import/provider boundary. It also checks React ErrorBoundary console errors, which do not necessarily emit pageerror.

Data Compatibility

Existing browser IndexedDB data, Yjs document shapes, export files, and Google Drive/Dropbox sync state are live user data.

  • Keep schema changes additive when possible.
  • Include explicit migrations for incompatible changes.
  • Preserve old entity shapes in validation and import paths.
  • Do not require users to clear browser data or Google Drive/Dropbox sync state.
  • Keep destructive sync, deletion, and billing actions explicit and reversible where practical.
  • Use existing Yjs hooks, stores, and command layers instead of adding parallel persistence.

Agent Bridge

The TaskTime Pro agent bridge is same-device only.

  • The browser app remains the mutation owner.
  • The bridge must stay loopback-only.
  • Pairing, scopes, approval tokens, and revocation behavior must remain explicit.
  • MCP tools should expose business actions, not raw storage access.
  • Generated tool docs and public agent docs should stay in sync with tool changes.

Public Repository Boundary

This repository intentionally excludes private Cloudflare Worker source, deployment configuration, secrets, provider account IDs, production KV/D1 identifiers, and internal operational runbooks.

Public code may reference public endpoints such as https://sync.tasktime.pro, but private implementation details belong outside this repo.

License

TaskTime Pro app and bridge code are licensed under AGPL-3.0-only.

The OpenClaw/ClawHub skill bundle in integrations/openclaw/tasktime/ is licensed under MIT-0.