Contributing to OpenCLM

OpenCLM is an open-source project and we welcome contributions of all kinds — bug fixes, new features, documentation improvements, and translations.

Development Setup

Prerequisites

• Node.js 20+
• pnpm (recommended) or npm
• Docker + Docker Compose (for the database)
• Git

Fork and Clone

git clone https://github.com/YOUR-USERNAME/openclm.git
cd openclm

Start the Development Stack

# Start only the database and Keycloak
docker compose -f docker-compose.dev.yml up -d db keycloak

# Install frontend dependencies
npm install

# Install backend dependencies
cd server && npm install && cd ..

# Copy env file
cp .env.example .env
# Edit .env with your local database settings

# Run migrations and seed
cd server
npx prisma migrate dev
npx prisma db seed
cd ..

# Start the development servers (frontend + API concurrently)
npm run dev

The app opens at http://localhost:3000.

Useful Development Commands

Command	Description
npm run dev	Start frontend + API in watch mode
npm run build	Production build of the frontend
cd server && npm run dev	Start API only
cd server && npx prisma studio	Open Prisma Studio (DB browser)
npm run lint	Run ESLint
npm run typecheck	Run TypeScript type-check
npm test	Run frontend unit tests
cd server && npm test	Run API unit tests
npm run test:e2e	Run Playwright end-to-end tests

Coding Standards

TypeScript

• All new code must be TypeScript. No any types — use proper types or unknown.
• Use zod for runtime validation of API inputs.

React

• Prefer functional components with hooks.
• Co-locate component files with their feature: src/components/contracts/ContractList.tsx.
• Keep components focused — split large components.

API Routes

• All routes must go through the requirePermission middleware.
• Input validation via Zod schemas — defined in server/src/schemas/.
• Use Prisma transactions for operations that modify multiple tables.

Commits

Follow Conventional Commits:

feat(contracts): add bulk archive action
fix(approvals): correct escalation timer calculation
docs(api): add pagination examples

Pull Request Process

1. Create a feature branch: git checkout -b feat/your-feature-name.
2. Write your code and tests.
3. Run npm run lint && npm run typecheck && npm test.
4. Push and open a PR against the main branch.
5. Fill in the PR template — describe what changed and why.
6. A maintainer will review within 5 business days.

Reporting Bugs

Open a GitHub Issue using the bug report template. Include:

• Steps to reproduce.
• Expected vs. actual behaviour.
• OpenCLM version (from Settings → About).
• Browser / OS if it's a UI issue.

Security Vulnerabilities

Do not open a public issue for security vulnerabilities. Instead, email [email protected] or use GitHub's private vulnerability reporting.

See SECURITY.md for the full disclosure policy.