Contributing

Meridian is open source under the Apache 2.0 license and welcomes contributions from the community. Whether you're fixing a bug, adding a feature, or improving documentation, this guide covers everything you need to get started.

Code of Conduct

All contributors are expected to follow the Contributor Covenant Code of Conduct. Please read it before participating.

Development setup

Prerequisites

• Node.js 18 or later
• pnpm (install with npm install -g pnpm)
• Git
• A Neon account (free tier) for the database
• An OpenAI API key for testing proxy endpoints (optional but recommended)

Setup steps

# 1. Fork the repo on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/meridian
cd meridian

# 2. Install dependencies
pnpm install

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your Neon DATABASE_URL and other values

# 4. Run database migrations
pnpm prisma migrate dev

# 5. Start the development server
pnpm dev

# 6. (Optional) Open Prisma Studio to inspect the database
pnpm prisma studio

The app will be running at http://localhost:3000.

Branch naming

Use a descriptive branch name with one of these prefixes:

Commit conventions

We follow Conventional Commits. Each commit message should have the format:

<type>: <description>

# Examples:
feat: add Anthropic Claude provider support
fix: correct token count for streaming responses
docs: update quickstart with Python examples
test: add integration tests for proxy key rotation
refactor: extract provider detection into shared utility

Valid types: feat, fix, docs, test, refactor, chore, ci.

Pull request process

1. Fork the repository and create a new branch from main.
2. Make your changes. Follow the coding standards below.
3. Write tests. All new features and bug fixes should include tests.
   Run tests

   pnpm test          # Unit + integration tests (Vitest)
   pnpm test:e2e      # End-to-end tests (Playwright)

4. Commit using Conventional Commits format.
5. Push your branch to your fork.
6. Open a pull request against main. Fill out the PR template checklist.
7. CI checks must pass (lint, typecheck, tests).
8. A maintainer will review your PR. Address any feedback and push updates.
9. Once approved, the PR will be squash-merged into main.

Coding standards

• TypeScript strict mode — no any types.
• ESLint + Prettier formatting. Run pnpm lint before committing.
• JSDoc comments on all exported functions.
• API routes return consistent error format: { error: string, code: string }.
• Business logic in /lib — route handlers should be thin wrappers.
• UI components receive data as props — no database calls inside components.
• Use shadcn/ui for all UI elements (buttons, cards, tables, dialogs, etc.).

Good first issues

Looking for a place to start? These issues are tagged as beginner-friendly:

Reporting bugs

Found a bug? Open an issue using the bug report template. Include steps to reproduce, expected vs actual behavior, and your environment details.

Suggesting features

Have an idea? Open an issue using the feature request template. Describe the problem, your proposed solution, and any alternatives you've considered.