chore: Add contributing guide, PR template and improve post-install (#1270)

charlesvien · web-flow · commit f51cc9338115 · 2026-03-20T15:03:49.000-07:00
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,15 @@
+## Problem
+
+<!-- Who is this for and what problem does it solve? -->
+
+<!-- Closes #ISSUE_ID -->
+
+## Changes
+
+<!-- What did you change and why? -->
+<!-- If there are frontend changes, include screenshots. -->
+
+## How did you test this?
+
+<!-- Describe what you tested -- manual steps, automated tests, or both. -->
+<!-- If you're an agent, only list tests you actually ran. -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,47 @@
+# Contributing to PostHog Code
+
+We love contributions big and small. PostHog Code is the IDE for understanding how users interact with your product -- and we want the community involved in shaping it.
+
+## Getting started
+
+1. Fork the repo and clone it locally
+2. Follow the [Development setup](#development-setup) below
+3. Create a branch (`feat/my-change`, `fix/that-bug`)
+4. Make your changes and open a pull request
+
+We recommend creating an issue first if one doesn't already exist so we can align on the approach before you invest time.
+
+## Development setup
+
+```bash
+# Prerequisites: Node.js 22+, pnpm 10.23+
+pnpm install
+cp .env.example .env
+pnpm dev
+```
+
+See [docs/LOCAL-DEVELOPMENT.md](./docs/LOCAL-DEVELOPMENT.md) for connecting to a local PostHog instance.
+
+## Before submitting
+
+- Run `pnpm typecheck`, `pnpm lint` and `pnpm test` locally
+- Resolve merge conflicts before requesting review
+- Keep changes focused -- one logical change per PR
+- Add tests where they meaningfully improve confidence
+- Follow existing patterns and conventions in the areas you touch (see [CLAUDE.md](./CLAUDE.md) for code style details)
+
+## What to expect
+
+- PRs are triaged and assigned to the relevant team
+- Expect acknowledgement within a few days. Thorough reviews may take longer depending on load
+- We sometimes close PRs that are out of scope or would add long-term maintenance burden. You're always welcome to reopen with updates
+
+## Issues
+
+Spotted a bug? Something broken? [Raise an issue](https://github.com/PostHog/code/issues/new) for the fastest response.
+
+## Feature requests
+
+Raise an issue and tag it as an enhancement. Give us as much context on the _why_ as possible -- we love hearing about the problem you're trying to solve.
+
+If you're unsure whether something fits, open an issue first and we'll get back to you quickly.
diff --git a/README.md b/README.md
@@ -92,10 +92,15 @@ posthog-code/
 | [apps/mobile/README.md](./apps/mobile/README.md) | Mobile app: Expo setup, EAS builds, and TestFlight deployment |
 | [apps/cli/README.md](./apps/cli/README.md) | CLI: stacked PR management with Jujutsu |
 | [CLAUDE.md](./CLAUDE.md) | Code style, patterns, and testing guidelines |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute to PostHog Code |
 | [docs/LOCAL-DEVELOPMENT.md](./docs/LOCAL-DEVELOPMENT.md) | Connecting PostHog Code to a local PostHog instance |
 | [docs/UPDATES.md](./docs/UPDATES.md) | Release versioning and git tagging |
 | [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) | Common issues and fixes |
 
+## Contributing
+
+We love contributions big and small. See [CONTRIBUTING.md](./CONTRIBUTING.md) to get started.
+
 ## Troubleshooting
 
 See [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) for common issues (black screen, Electron install failures, native module crashes, etc.).
diff --git a/apps/code/package.json b/apps/code/package.json
@@ -25,7 +25,7 @@
     "test": "vitest run",
     "test:e2e": "playwright test --config=tests/e2e/playwright.config.ts",
     "test:e2e:headed": "playwright test --config=tests/e2e/playwright.config.ts --headed",
-    "postinstall": "cd ../.. && npx @electron/rebuild -f -m node_modules/node-pty && npx @electron/rebuild -f -m node_modules/better-sqlite3 || true && bash apps/code/scripts/patch-electron-name.sh && node apps/code/scripts/download-binaries.mjs",
+    "postinstall": "bash scripts/postinstall.sh",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "clean": "rm -rf .vite .turbo out node_modules/.vite",
diff --git a/apps/code/scripts/postinstall.sh b/apps/code/scripts/postinstall.sh
@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# Postinstall script for the Electron app
+# Rebuilds native modules against Electron's Node headers and applies patches
+
+set -e
+
+REPO_ROOT="$(cd ../.. && pwd)"
+SCRIPTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "Rebuilding native modules for Electron..."
+
+cd "$REPO_ROOT"
+npx @electron/rebuild -f -m node_modules/node-pty
+npx @electron/rebuild -f -m node_modules/better-sqlite3 || true
+
+echo "Patching Electron app name..."
+bash "$SCRIPTS_DIR/patch-electron-name.sh"
+
+echo "Downloading binaries..."
+node "$SCRIPTS_DIR/download-binaries.mjs"
+
+echo "Postinstall complete."
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -45,10 +45,12 @@ If the app crashes with something like:
 libc++abi: terminating due to uncaught exception of type Napi::Error
 ```
 
-Native modules (like node-pty) need to be rebuilt for your Electron version:
+Native modules (like node-pty) need to be rebuilt for your Electron version.
+
+### Fix
 
 ```bash
-pnpm --filter code exec electron-rebuild
+cd apps/code && npx electron-rebuild -f
 ```
 
 ## Codex agent crashes with GPU process errors
@@ -70,24 +72,56 @@ node apps/code/scripts/download-binaries.mjs
 
 Then restart the app. This downloads the codex-acp binary to `apps/code/resources/codex-acp/`, which gets copied to `.vite/build/codex-acp/` during build.
 
-## Database initialization failed (better-sqlite3 bindings not found)
+## Database initialization failed (better-sqlite3)
 
-If you see this error on startup:
+If you see either of these errors on startup:
 
 ```
 Database initialization failed Error: Could not locate the bindings file.
 ```
 
-The `better-sqlite3` native binary wasn't compiled for your Electron version. This commonly happens after a merge, branch switch or fresh install because the postinstall rebuild can fail silently (`|| true`).
+```
+Database initialization failed Error: The module '.../better_sqlite3.node'
+was compiled against a different Node.js version using
+NODE_MODULE_VERSION 145. This version of Node.js requires
+NODE_MODULE_VERSION 123.
+```
+
+The `better-sqlite3` native binary wasn't compiled for your Electron version. This commonly happens after a merge, branch switch or Electron upgrade because the postinstall rebuild can fail silently (`|| true`).
 
 ### Fix
 
 ```bash
-npx @electron/rebuild -f -m node_modules/better-sqlite3
+cd apps/code && npx electron-rebuild -f
 ```
 
 Then restart the app.
 
+## node-gyp failed to rebuild @parcel/watcher
+
+If you see this error after pulling or switching branches:
+
+```
+Error: node-gyp failed to rebuild '/path/to/node_modules/@parcel/watcher'
+```
+
+`@parcel/watcher` ships prebuilt N-API binaries per platform (e.g. `@parcel/watcher-darwin-arm64`) and should not need recompilation. This error usually means a stale or partial install state is triggering a source rebuild that fails.
+
+### Fix
+
+```bash
+rm -rf node_modules/@parcel/watcher
+pnpm install
+```
+
+If that doesn't work, nuke and reinstall:
+
+```bash
+rm -rf node_modules && pnpm install
+```
+
+Do **not** run `npx @electron/rebuild` against `@parcel/watcher` — it doesn't need it and the rebuild will fail.
+
 ## `pnpm i` shows "Packages: -198"
 
 You might see something like this every time you run `pnpm install`:
