Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
131 lines (90 loc) · 3.64 KB

CONTRIBUTING.md

File metadata and controls

131 lines (90 loc) · 3.64 KB

Contributing

Thanks for your interest in TTDash.

This project is currently maintained by a single maintainer. Contributions are welcome, but acceptance is selective so the codebase, scope, and release quality stay manageable.

What Is Most Helpful

The easiest changes to review and merge are:

  • reproducible bug reports
  • documentation fixes and clarifications
  • focused bugfix pull requests
  • small UX or accessibility improvements
  • tests that cover existing or clearly agreed behavior

Please open an issue before spending time on larger changes such as:

  • new features
  • architectural refactors
  • dependency swaps
  • changes to import, persistence, or reporting behavior
  • broad UI redesigns

Large unsolicited pull requests may be declined even if they are technically correct, simply because they do not fit the current direction or available review time.

Before You Open an Issue

Please include enough detail for the problem to be actionable:

  • what you expected
  • what actually happened
  • exact steps to reproduce
  • sample input data if the bug depends on input shape
  • screenshots or terminal output when helpful
  • environment details when relevant: OS, Node version, install method, browser

For feature requests, explain the user problem first. Suggestions that only describe an implementation without clarifying the problem are harder to evaluate.

Before You Open a Pull Request

Make sure the change is small, focused, and aligned with the existing product direction.

Run the main local checks:

npm run verify
npm run test:e2e

npm run verify covers formatting, ESLint, tsc --noEmit, unit tests, the production bundle, and packaged-artifact verification. If you want the same coverage gate used in release preparation, also run:

npm run test:unit:coverage

If you only need the production bundle without the lint/format gate, use:

npm run build:app

If local port 3015 is already occupied, run Playwright on another isolated port:

PLAYWRIGHT_TEST_PORT=3016 npm run test:e2e

The Playwright suite uses an isolated local app directory under .tmp-playwright/ and should not reuse your normal local dashboard data. npm run verify:package builds the real tarball and verifies that the packaged CLI can start outside the repo checkout.

Then manually verify the main user flows touched by your change:

  • dashboard load
  • auto-import
  • JSON upload
  • filtering
  • CSV/PDF export when relevant

If you change dependencies, update both lockfiles so npm and Bun installs stay reproducible:

npm install
bun install --lockfile-only

Pull Request Expectations

Good pull requests are:

  • narrowly scoped
  • easy to review commit-by-commit
  • consistent with the existing code style
  • explicit about user-visible behavior changes

Please include:

  • a short summary of the change
  • why the change is needed
  • how you tested it
  • screenshots or terminal output for UI/CLI changes when helpful

Development Setup

npm install
npm run dev
node server.js

Or with Bun:

bun install
bun run dev
node server.js

The frontend dev server runs on http://localhost:5173 and the local API/static server runs on http://localhost:3000.

Style

  • Frontend: TypeScript + React, 2-space indentation, single quotes, no semicolons in src/
  • Server: CommonJS, keep existing semicolon style in server.js
  • Keep feature UI colocated under src/components/features/
  • Prefer small, targeted changes over broad cleanup refactors

Related Docs