Skip to content

Contributing

Thank you for contributing to Tally! This guide walks you through everything needed to set up your environment, run the checks, and submit a pull request.

Prerequisites

Tool Recommended version Install
Bun ≥ 1.0 curl -fsSL https://bun.sh/install \| bash
Git any modern version system package manager

Node.js users — The project was authored with Bun but the standard npm/Node toolchain works too (npm install, npm run dev, etc.).

1 — Fork and clone

# Fork the repo on GitHub, then:
git clone https://github.com/<your-username>/Tally.git
cd Tally

2 — Install dependencies

bun install

3 — Start the development server

bun run dev

Open http://localhost:5173. The server hot-reloads on every file change — no restart needed.

4 — Development workflow

Lint

bun run lint

Uses ESLint with the TypeScript and React-Hooks plugins. Config lives in eslint.config.js.

Type-check + build

bun run build

Runs tsc -b (strict TypeScript) followed by vite build. A successful build writes output to dist/.

Unit tests

bun run test          # run once
bun run test:watch    # watch mode — reruns on file changes

Uses Vitest with the jsdom environment. Test files live next to the source they test (e.g. src/persistence.test.ts).

All checks in one shot

bun run lint && bun run test && bun run build

All three must pass before a PR is ready for review.

5 — Writing tests

  • Place test files alongside their source: src/foo.test.ts tests src/foo.ts.
  • Use Vitest's describe / it / expect globals (no import needed — configured in vite.config.ts).
  • Pure utility functions should be unit-tested; React components can be integration-tested with jsdom if the logic is non-trivial.
  • Aim for behaviour coverage, not line coverage.

6 — Coding standards

  • TypeScript — all new files must be .ts / .tsx with strict types. Avoid any; use unknown + type narrowing instead.
  • React — functional components only; state via hooks. No class components, no innerHTML, no DOM refs for data.
  • Formatting — the project does not enforce a formatter yet; match the style of the file you are editing (2-space indent, single quotes).
  • Imports — use relative imports within src/; no barrel index.ts re-exports unless they already exist.
  • Persistence — all localStorage access must go through src/persistence.ts. Do not call localStorage directly elsewhere.
  • XSS — run user-supplied strings through esc() (src/utils/esc.ts) before inserting them into markup.

7 — Submitting a pull request

  1. Create a feature branch from main: 
    git checkout -b feat/my-feature
  2. Make your changes, commit with a clear message (see PR & Issue Hygiene).
  3. Push and open a pull request on GitHub.
  4. The CI pipeline (lint → test → build) must be green before merging.
  5. Address review feedback and re-push; the PR auto-updates.

See PR & Issue Hygiene for title conventions and checklist requirements.

8 — Documentation site

User-facing documentation is maintained in the public TallyDocs repository and published at auxkit.github.io/TallyDocs.

To edit or preview the docs locally:

git clone https://github.com/auxkit/TallyDocs.git
cd TallyDocs
python -m venv .venv-docs
source .venv-docs/bin/activate   # Windows: .venv-docs\Scripts\activate
pip install -r requirements-docs.txt
mkdocs serve                     # http://127.0.0.1:8000
mkdocs build --strict            # validate before opening a PR

When you change architecture or contribution workflow in the app, open a matching PR against TallyDocs so the published site stays accurate.