Contributing to OpenCut

Thank you for your interest in contributing to OpenCut! This document provides guidelines and instructions for contributing.

Getting Started

Fork the repository
Clone your fork locally
Navigate to the web app directory: cd apps/web
Install dependencies: bun install
Start the development server: bun run dev

Note: If you see an error like Unsupported URL Type "workspace:*" when running npm install, you have two options:

Upgrade to a recent npm version (v9 or later), which has full workspace protocol support.

Use an alternative package manager such as bun or pnpm.

Development Setup

Prerequisites

Node.js 18+
Bun (latest version)
Docker (for local database)

Local Development

Start the database and Redis services:

# From project root
docker-compose up -d

Navigate to the web app directory:
```
cd apps/web
```

Copy .env.example to .env.local:

# Unix/Linux/Mac
cp .env.example .env.local

# Windows Command Prompt
copy .env.example .env.local

# Windows PowerShell
Copy-Item .env.example .env.local

Configure required environment variables in .env.local:

Required Variables:

# Database (matches docker-compose.yaml)
DATABASE_URL="postgresql://opencut:opencutthegoat@localhost:5432/opencut"

# Generate a secure secret for Better Auth
BETTER_AUTH_SECRET="your-generated-secret-here"
BETTER_AUTH_URL="http://localhost:3000"

# Redis (matches docker-compose.yaml)
UPSTASH_REDIS_REST_URL="http://localhost:8079"
UPSTASH_REDIS_REST_TOKEN="example_token"

# Development
NODE_ENV="development"

Generate BETTER_AUTH_SECRET:

# Unix/Linux/Mac
openssl rand -base64 32

# Windows PowerShell (simple method)
[System.Web.Security.Membership]::GeneratePassword(32, 0)

# Cross-platform (using Node.js)
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Or use an online generator: https://generate-secret.vercel.app/32

Optional Variables (for Google OAuth):

# Only needed if you want to test Google login
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

Run database migrations: bun run db:migrate
Start the development server: bun run dev

How to Contribute

Reporting Bugs

Use the bug report template
Include steps to reproduce
Provide screenshots if applicable

Suggesting Features

Use the feature request template
Explain the use case
Consider implementation details

Code Contributions

Create a new branch: git checkout -b feature/your-feature-name
Make your changes
Navigate to the web app directory: cd apps/web
Run the linter: bun run lint
Format your code: bunx biome format --write .
Commit your changes with a descriptive message
Push to your fork and create a pull request

Code Style

We use Biome for code formatting and linting
Run bunx biome format --write . from the apps/web directory to format code
Run bun run lint from the apps/web directory to check for linting issues
Follow the existing code patterns

Pull Request Process

Fill out the pull request template completely
Link any related issues
Ensure CI passes
Request review from maintainers
Address any feedback

Community

Be respectful and inclusive
Follow our Code of Conduct
Help others in discussions and issues

Thank you for contributing!

3.6 KiB Raw Blame History