Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
108 lines (72 loc) · 3.14 KB

CONTRIBUTING.md

File metadata and controls

108 lines (72 loc) · 3.14 KB
Raw

Contributing to Juxta

Thank you for taking the time to contribute. This document covers everything you need to get set up and submit a quality pull request.

Prerequisites

  • Bun ≥ 1.0 — used as the runtime, package manager, and test runner
  • Playwright browsers for end-to-end tests (installed separately — see below)

Setup

# 1. Fork & clone the repository
git clone https://github.com/<your-fork>/Juxta.git
cd Juxta

# 2. Install dependencies
bun install

# 3. Install Playwright browsers (first time only)
bunx playwright install --with-deps

Development Loop

# Start the dev server with hot reload on port 3000
bun run dev

Edit files under src/. SvelteKit will reload the browser automatically.

The Gate — All Four Must Pass Before You Push

bun run check      # Svelte + TypeScript type-check (0 errors required)
bun test           # Unit tests
bun run test:e2e   # Playwright end-to-end tests
bun run build      # Production build (confirms no build-time errors)

All four checks also run in CI on every pull request. A failing check blocks merge.

Branching & Commit Convention

  • Branch off main. Name your branch descriptively: feat/my-feature or fix/issue-123.
  • Use Conventional Commits for commit messages:
    • feat: — new user-visible feature
    • fix: — bug fix
    • chore: — maintenance (deps, config, tooling)
    • docs: — documentation only
    • test: — adding or fixing tests
    • refactor: — code restructure with no behaviour change
  • Subject line ≤ 72 characters. Imperative mood ("add X", not "added X").
  • Do not include AI-authorship trailers (Co-Authored-By: Claude, Generated by, etc.).

Pull Request Process

  1. Ensure all four gate checks pass locally.
  2. Open a pull request against main and fill in the PR template.
  3. A maintainer will review within a reasonable time. Address feedback with new commits (do not force-push review history away).
  4. Once approved and CI green, a maintainer will merge.

Code Style

  • Svelte 5 runes ($state, $derived, $effect, etc.) — use the runes API, not the legacy options API.
  • Tailwind CSS — preserve existing utility class names; do not introduce a second styling system.
  • No runtime dependencies in the diff engine (src/lib/diff/); keep it pure TypeScript.
  • TypeScript strict mode is on. Do not use any without a comment explaining why.
  • There is no ESLint config — bun run check (svelte-check) is the linter.

Running Individual Tests

# Run a single unit test file
bun test src/lib/diff/engine.test.ts

# Run a single Playwright spec
bunx playwright test e2e/diff.spec.ts

Reporting Issues

Use the GitHub issue tracker. Please fill in the bug or feature template fully — incomplete reports are harder to action.

License

By contributing, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0, the same licence as the project.