Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
228 lines (155 loc) · 6.9 KB

CONTRIBUTING.md

File metadata and controls

228 lines (155 loc) · 6.9 KB
Raw

Contributing to OpenCoven Feedback

Thank you for your interest in contributing to OpenCoven Feedback! This guide will help you get started.

Quick Start

# Clone the repository
git clone https://github.com/quackbackio/quackback.git
cd quackback

# Run setup (installs dependencies, starts Docker, runs migrations, seeds demo data)
bun run setup

# Start development server
bun run dev

Open http://localhost:3000 to see the app.

Project Structure

quackback/
├── apps/web/              # TanStack Start application
│   ├── src/
│   │   ├── routes/        # File-based routing (TanStack Router)
│   │   ├── components/    # UI and feature components
│   │   └── lib/           # Business logic, auth config, services
│   └── e2e/               # Playwright E2E tests
├── packages/
│   ├── db/                # Database (Drizzle schema, migrations)
│   ├── ids/               # TypeID system (branded UUIDs)
│   └── email/             # Email service (Resend + React Email)
├── ee/                    # Enterprise Edition features (SSO, SCIM, etc.)
└── docker-compose.yml     # Local PostgreSQL 18

Architecture

Quackback uses TanStack Start with TanStack Router for file-based routing and server functions.

Server Functions (apps/web/src/lib/server-functions/)

Type-safe RPC endpoints using createServerFn:

import { createServerFn } from '@tanstack/react-start'
import { z } from 'zod'

export const createPostFn = createServerFn({ method: 'POST' })
  .validator(z.object({ title: z.string().min(1) }))
  .handler(async ({ data }) => {
    const auth = await requireAuth()
    return createPost(data, auth.member)
  })

Service Layer (apps/web/src/lib/{feature}/)

Business logic with typed error handling:

import { ValidationError } from '@/lib/shared/errors'

export async function createPost(input: CreatePostInput, author: Author) {
  if (!input.title?.trim()) {
    throw new ValidationError('VALIDATION_ERROR', 'Title is required')
  }
  // Business logic...
}

Database Access

Always import from @/lib/db, not @quackback/db:

import { db, posts, eq } from '@/lib/db'

const post = await db.query.posts.findFirst({
  where: eq(posts.id, postId),
})

Architecture

  • Single workspace, DATABASE_URL singleton

Development Guidelines

Code Style

  • Files: kebab-case (user-profile.tsx)
  • Components: PascalCase (UserProfile)
  • Functions: camelCase (getUserProfile)
  • Database tables: snake_case (post_tags)

Testing

# Run all tests
bun run test

# Run specific test file
bun run test path/to/test.ts

# Run E2E tests
bun run test:e2e

Contributor License Agreement

We require all contributors to sign our Contributor License Agreement (CLA) before we can accept contributions.

Why a CLA?

The CLA allows Quackback to:

  • Offer the software under dual licenses (AGPL-3.0 for open source, commercial for enterprise)
  • Defend the project against legal issues
  • Ensure clean IP ownership for all contributions

How it works:

  1. Submit your pull request
  2. A CLA assistant bot will check if you've signed the CLA
  3. If not, the bot will prompt you to sign by commenting on the PR
  4. Once signed, your signature applies to all future contributions

The CLA is based on the Apache Individual Contributor License Agreement and grants Quackback the right to use your contributions under any license terms.

Pull Request Process

  1. Fork the repository
  2. Create a feature branch from main
  3. Make your changes
  4. Ensure all tests pass
  5. Submit a pull request
  6. Sign the CLA when prompted by the bot

PR Guidelines

  • Keep PRs focused and reasonably sized
  • Include tests for new functionality
  • Update documentation if needed
  • Follow the existing code style

Reporting Issues

Please use GitHub Issues for:

  • Bug reports
  • Feature requests
  • Questions

When reporting bugs, include:

  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, browser, etc.)

License

Quackback core is licensed under AGPL-3.0. See LICENSE for details.

OpenCoven DCO and Patent Terms

Thank you for your interest in contributing. OpenCoven is MIT licensed and community-driven. We want contributing to be easy, open, and safe for everyone.

Developer Certificate of Origin (DCO)

OpenCoven uses the Developer Certificate of Origin (DCO) v1.1 for all contributions. This is a lightweight mechanism — not a CLA — that asks you to certify that you have the right to submit what you're submitting.

By making a contribution to this project, you certify that:

(a) The contribution was created in whole or in part by you and you have the right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of your knowledge, is covered under an appropriate open source license and you have the right under that license to submit that work with modifications, whether created in whole or in part by you, under the same open source license (unless you are permitted to submit under a different license), as indicated in the file; or

(c) The contribution was provided directly to you by some other person who certified (a), (b) or (c) and you have not modified it.

(d) You understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information you submit with it, including your sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

How to Sign Off

Add a Signed-off-by line to your commit message:

git commit -s -m "Your commit message"

This produces:

Your commit message

Signed-off-by: Your Name <your.email@example.com>

Patent Non-Assertion

By contributing, you additionally agree not to assert any patent claims — now held or later acquired — against this project or its users that arise from your contribution. See PATENTS for the full non-assertion pledge.

What We're Looking For

  • Bug fixes and reliability improvements
  • Documentation and example improvements
  • New skills, tools, and integrations
  • Performance improvements
  • Community-requested features

What We're Not

OpenCoven is not a contribution vehicle for proprietary forks. If you are building a closed-source derivative of OpenCoven's architecture, please do not use contribution as a means to learn implementation details that are not yet public. We welcome genuine collaborators.

Getting Started

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-feature
  3. Make your changes with signed-off commits: git commit -s
  4. Open a pull request with a clear description

Questions?

Join the Discord: https://discord.gg/OpenCoven