Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (80 loc) · 5.1 KB

CONTRIBUTING.md

File metadata and controls

132 lines (80 loc) · 5.1 KB
Raw

Contributing to kaichen.dev

Thank you for reading this. kaichen.dev is primarily a personal site, but bug fixes, documentation improvements, and small, focused enhancements are welcome.

Before you contribute:

  1. Read CODE_OF_CONDUCT.md.
  2. Read SECURITY.md — never file public issues with exploit details.
  3. Skim the README for architecture, scripts, and environment variables.

Who this guide is for

Audience Also read
Human contributors This file + README
AI coding agents (Cursor, Claude Code, etc.) AGENTS.md — branch + PR workflow and commit conventions are mandatory

All changes go through pull requests to main; do not push directly to main, even when permissions allow.

Prerequisites

  • Node.js 20 (matches CI and @types/node in package.json).
  • npm — the repo uses package-lock.json. For reproducible installs use npm ci (as CI does).

Clone and install

git clone https://github.com/kaiiiichen/kaichen.dev.git
cd kaichen.dev
npm install
cp .env.example .env.local

Edit .env.local as needed. You do not need every integration to run the app locally:

  • Missing Spotify / GitHub keys usually degrade specific widgets.
  • Supabase is optional for /api/spotify/now-playing only; next build succeeds without Supabase env (see README — Environment variables, subsection CI builds without live Supabase).

Never commit .env.local, .env.vercel.check, tokens, or SENTRY_AUTH_TOKEN.

Git hooks (after npm install)

package.json runs postinstall to set git config core.hooksPath .githooks. The prepare-commit-msg hook appends a Co-authored-by trailer for Claude on each commit (see AGENTS.md). If your environment skips hooks (e.g. some UIs), add the trailer manually when required by project policy.

Mandatory checks (same as CI)

Before opening or updating a PR, run:

npm run lint
npm run typecheck
npm run test
npm run build

.github/workflows/ci.yml runs these steps on push and pull_request to main. Keep CI green.

Branch and pull request workflow

  1. Branch from up-to-date main:

    git checkout main && git pull --ff-only
git checkout -b <type>/<short-description>

    Prefix examples: fix/, feat/, chore/, docs/, refactor/.

  2. Commit with clear messages (conventional style is appreciated: type: summary).

  3. Push and open a PR against main. GitHub will suggest the pull request template.

  4. Describe what changed and why. Link issues with Fixes #123 when applicable.

  5. Update README.md and/or .env.example if you change user-visible behavior, new routes, or required/optional environment variables.

Project conventions

Stack and rendering

  • Next.js 16 App Router, React 19, TypeScript, Tailwind CSS 4, Vitest 4 for unit tests.
  • dev and build use Next.js' default Turbopack bundler (no MDX in this repo).
  • Fonts: Geist Sans/Mono provide the base type system; Nunito is used across the editorial UI (nav, headings, cards, lists, and controls). See app/globals.css, app/layout.tsx, and app/fonts.ts.

Style

  • Match existing component patterns, naming, and Tailwind usage.
  • Preserve the shared interaction palette: structural/link blue (--link-color), yellow hover/focus (--link-hover-color), and the layered blue .mag-card border/shadow hierarchy.
  • Keep PageToc discovery intact when restructuring pages: prefer explicit TocSection targets or existing .mag-label sections, and exclude fullscreen routes such as /music-for-life/map.
  • Prefer small, reviewable diffs over large refactors unless discussed in an issue first.
  • Dark mode: new UI should work in light and dark (dark: variants and existing theme patterns).

Secrets and config

  • Add variable names (and short comments) to .env.example when introducing new configuration — never real secrets.
  • Do not add production keys, personal tokens, or Sentry auth tokens to the repository.

Security-sensitive areas

If you touch OAuth callbacks, API routes, or Supabase policies, coordinate with the maintainer and document behavior in README or SECURITY as appropriate.

Forking for your own site

See the Forking this project section in README.md for a checklist of files to replace (Spotify app, GitHub repos, Supabase, etc.).

Issues

Use issue templates for bugs and features. For security issues, follow SECURITY.md instead of posting exploit details in public issues.

Questions

For small questions, open a GitHub Issue or Discussion. This is a side project; response time may vary.