Contributor Guide
Relevant source files
The following files were used as context for generating this wiki page:
Kocteau is an open-source music review and taste discovery application built with a focus on human taste and editorial curation. The project follows a web-first contribution path, primarily targeting the apps/web directory while maintaining apps/mobile as a future-facing target.
Sources: CONTRIBUTING.md:3-5, README.md:12-14
This guide outlines the technical requirements, local development workflows, and philosophical principles necessary for contributing to the Kocteau ecosystem. It emphasizes small, focused contributions such as UI polish, documentation improvements, and accessibility fixes as the best entry points for new developers.
Sources: CONTRIBUTING.md:7-16, README.md:46-48
Core Development Philosophy
Contributors must adhere to "Product Truths" that define Kocteau as an editorial, human-led experience rather than a generic social network. The core loop prioritizes music reviews, taste expression, and discovery via the "For You" feed.
Sources: AGENTS.md:10-18
Design Engineering Principles
- Minimalism: Maintain a dark, editorial, and monochrome visual direction.
- Restraint: Use color only for rating accents or album art; avoid loud gradients or "SaaS-like" patterns.
- Stability: Keep dimensions stable to avoid layout shifts.
- Quietness: Favor micro-polish and subtle dividers over excessive badges or colorful pills.
Sources: AGENTS.md:61-104
Environment Setup
Kocteau uses a local-first development strategy utilizing the Supabase CLI. Contributors should not require production credentials for standard web development.
Local Workflow Sequence
The diagram above illustrates the standard command sequence to initialize a local development environment.
Sources: CONTRIBUTING.md:21-29, README.md:111-120
Required Environment Variables
Configuration must be placed in apps/web/.env.local using values provided by pnpm supabase:status.
| Variable | Description | Default/Example |
|---|---|---|
NEXT_PUBLIC_SITE_URL | The local or production site URL | http://localhost:3000 |
NEXT_PUBLIC_SUPABASE_URL | Local Supabase API endpoint | http://127.0.0.1:54321 |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY | Local Supabase anon key | (From supabase status) |
Sources: CONTRIBUTING.md:31-35, README.md:95-103
Technical Stack and Boundaries
The project utilizes a specific set of technologies and architectural boundaries that contributors must respect.
Technology Stack
- Framework: Next.js (App Router)
- Language: TypeScript
- Styling: Tailwind CSS + shadcn/ui
- Backend/Auth: Supabase (Postgres, RLS, RPCs, Storage)
- Data Fetching: TanStack Query
- Emails: React Email + Resend (via Supabase SMTP)
Sources: README.md:81-91, AGENTS.md:47-56
Component Architecture
Contributors should default to Server Components where possible. Client Components are reserved for interactive elements, dialogs, optimistic actions, and keyboard shortcuts.
Sources: AGENTS.md:318-326
Contribution Workflow
Pull Request Requirements
Pull requests must be narrow in scope and include:
- Explanation: What changed and why.
- Verification: How the change was checked.
- Visuals: Screenshots or recordings for UI changes.
- Formatting: Clear titles following Conventional Commits (e.g.,
fix(web): ...).
Sources: CONTRIBUTING.md:46-63, README.md:55-57
Pre-submission Checks
Before opening a PR, contributors must run the following checks from the root:
pnpm supabase:lint
pnpm --filter web lint
pnpm --filter web build
git diff --check
Sources: CONTRIBUTING.md:39-44, README.md:124-129
Release Automation
Kocteau uses Release Please to automate versioning and changelog generation. Contributors must not manually edit CHANGELOG.md.
This diagram shows how commit messages drive the automated release process.
Sources: CONTRIBUTING.md:51-53, 73-77, release-please-config.json
Security and Sensitive Areas
Certain architectural areas require explicit maintainer discussion before modification:
- Database: Supabase schema, SQL migrations, RLS policies, or RPCs.
- Authentication: OTP flows, sessions, or permission logic.
- Core Logic: Recommendation algorithms, feed ranking, and analytics.
- DevOps: CI/CD pipelines, package manager configs, and deployment settings.
Sources: CONTRIBUTING.md:65-71, SECURITY.md:18-24
Vulnerability Reporting
Security issues must be reported privately via GitHub's private vulnerability reporting system. Public issues for exploitable bugs are prohibited.
Sources: SECURITY.md:5-10, SUPPORT.md:13-14
Summary
The Kocteau Contributor Guide establishes a framework for maintaining a high-quality, editorial music platform. By following the local-first Supabase workflow, adhering to monochrome design principles, and leveraging automated release tools, contributors help sustain a focused and "quiet" music discovery experience.
Sources: AGENTS.md:10-18, 417-427