Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (79 loc) · 2.85 KB

CONTRIBUTING.md

File metadata and controls

112 lines (79 loc) · 2.85 KB

Contributing to LiveSQL

Thanks for your interest in contributing! LiveSQL is an open-source project and we welcome contributions of all kinds.

Getting Started

Prerequisites

  • Node.js 20+
  • pnpm (npm install -g pnpm)
  • Docker (for PostgreSQL with wal_level=logical)

Setup

git clone https://github.com/mahabubul470/LiveSQL.git
cd LiveSQL
pnpm install

# Start test PostgreSQL
docker compose -f docker-compose.test.yml up -d

# Build all packages
pnpm build

# Run tests
pnpm test

Package Structure

packages/core       → Shared types and wire protocol (zero dependencies)
packages/server     → WAL CDC engine + WebSocket server (depends on core)
packages/client     → Framework-agnostic browser client (depends on core)
packages/react      → React hooks (depends on client)
packages/vue        → Vue composables (depends on client)
packages/svelte     → Svelte stores (depends on client)

Each package builds independently: pnpm --filter @livesql/<package> build

Development Workflow

  1. Fork the repo and create a branch from main:

    feat/my-feature
fix/bug-description
docs/update-something

  2. Make your changes and add tests (vitest)

  3. Run checks:

    pnpm test        # all tests
pnpm lint        # eslint + prettier
pnpm typecheck   # TypeScript strict mode

  4. Open a pull request against main

Coding Conventions

  • TypeScript strict mode — strict: true, exactOptionalPropertyTypes: true, noUncheckedIndexedAccess: true
  • Files: kebab-case.ts
  • Classes: PascalCase
  • Functions/variables: camelCase
  • Constants: UPPER_SNAKE_CASE
  • Interfaces: PascalCase (no I prefix)
  • Use interface for object shapes, type for unions/intersections
  • Use BigInt for offsets and LSNs
  • Export types explicitly — no export *

Commit Messages

Use conventional commits:

feat(core): add ChangeEvent wire protocol types
fix(server): prevent WAL slot leak on disconnect
test(integration): add reconnection backfill test
docs: update architecture diagram

Running Specific Tests

# Unit tests for a package
pnpm --filter @livesql/server test

# Integration tests (requires Docker PostgreSQL)
pnpm --filter integration test

# Chaos tests
npx vitest run --config tests/chaos/vitest.config.ts tests/chaos/

Architecture

Before diving into the code, read these docs:

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.