pad/CONTRIBUTING.md

Contributing to Pad

Thanks for your interest in contributing to Pad! This guide will help you get set up and familiar with how we work.

Where to start

Pad is built with Pad — we track our own work as Pad items and mirror the newcomer-friendly ones to GitHub. If you're looking for something to pick up, start with these labels:

• good first issue — small, self-contained, one focused PR.
• help wanted — a bit bigger, still scoped to a single PR.

Each issue states the problem, the concrete fix, and pointers to the relevant files. Area labels (area:cli, area:web, area:ci) tell you where the code lives; effort:S / effort:M set expectations.

How PRs are triaged: open a draft PR early and link the issue — a maintainer reviews within a few days. Small, focused PRs merge fastest: one issue, one branch. Comment on an issue to claim it before you start so we don't double up.

Found a problem that isn't an issue yet? Open one describing it (and how to reproduce, for bugs) before writing code, so we can agree on the approach first.

Getting Started

Prerequisites

• Go 1.26+
• Node.js 22+
• Make

Setup

git clone https://github.com/PerpetualSoftware/pad
cd pad
make build    # Build web UI + Go binary

This produces a ./pad binary in the project root.

Development

make build      # Full build: web UI + Go binary
make build-go   # Go only (skip web — faster for backend changes)
make dev-web    # SvelteKit dev server with hot reload (localhost:5173)
make test       # Run Go tests
make lint       # Run go vet
make install    # Build, install to ~/.local/bin/pad, restart server

Typical workflow:

1. Make your changes
2. make build to verify everything compiles
3. make test to run tests
4. make install to test the full binary locally
5. Open http://localhost:7777 to verify the web UI

Project Structure

cmd/pad/main.go          — CLI entry point (Cobra commands)
internal/
  server/                — HTTP API handlers, SSE, middleware
  store/                 — SQLite CRUD, migrations, FTS
  models/                — Go types
  items/                 — Field validation
  collections/           — Default schemas, templates
  cli/                   — HTTP client, formatting
  events/                — EventBus for real-time SSE
  config/                — Workspace detection
web/src/
  routes/                — SvelteKit pages
  lib/api/client.ts      — TypeScript API client
  lib/types/index.ts     — TypeScript types
  lib/components/        — Reusable UI components
skills/pad/SKILL.md      — Claude Code agent skill

Making Changes

Branch Naming

Use descriptive branch names:

• feat/relation-field-picker — new features
• fix/dashboard-progress-bar — bug fixes
• docs/update-api-reference — documentation
• refactor/store-interface — refactoring

Commit Messages

Write clear, concise commit messages that explain why, not just what:

Add phase relation field to Tasks collection

Tasks can now be linked to phases via a relation field,
enabling progress tracking on the phase detail page.

Pull Requests

• Keep PRs focused — one feature or fix per PR
• Include a description of what changed and why
• Add tests for new backend functionality
• Verify make build and make test pass before opening

Code Style

• Go: Standard gofmt formatting. Run go vet ./... to catch issues.
• Svelte: Follow existing component patterns. Use Svelte 5 runes ($state, $derived, $effect).
• TypeScript: Types live in web/src/lib/types/index.ts.

Quality Gates

PR CI runs two security gates that block merging on regressions:

• npm run audit:ci (from web/; make web-audit from the root) — npm audit --audit-level=high --omit=dev through web/scripts/ci-audit.mjs, which fails on any HIGH or CRITICAL advisory in production frontend deps and, separately, fails under its own title when the advisory service cannot be reached (after retries) rather than passing. CI runs it after build, svelte-check and vitest so those verdicts exist either way; make check does the same.
• make vuln (govulncheck -mode binary) — builds the pad binary and scans it for known vulnerabilities in any Go package it actually reaches. Runs in binary mode rather than source mode (govulncheck ./...): source mode builds an SSA call-graph over the whole dependency tree and can consume multiple GB of RAM (BUG-2084), while binary mode reads the compiled binary's symbol table for a fraction of the memory. Pinned to a specific govulncheck version in .github/workflows/ci.yml; bump intentionally rather than tracking @latest.

Both are fast enough to run locally:

make web-audit
make vuln

Adding Features

New API Endpoint

1. Add handler in internal/server/handlers_*.go
2. Register route in internal/server/server.go (setupRouter())
3. Add store method in internal/store/ if needed
4. Add CLI client method in internal/cli/client.go
5. Add TypeScript type in web/src/lib/types/index.ts
6. Add API method in web/src/lib/api/client.ts

New CLI Command

1. Add function in cmd/pad/main.go
2. Register in rootCmd.AddCommand()

Database Migration

1. Add migration in internal/store/migrations/
2. Update models in internal/models/
3. Migrations run automatically on server start

Reporting Issues

• Bugs: Use the bug report template — include steps to reproduce
• Features: Use the feature request template — describe the problem first, then your proposed solution
• Questions: Open a discussion or issue

Contributor License Agreement

By submitting a pull request, you agree to the terms of our Contributor License Agreement. This is a lightweight CLA that preserves your rights while granting the project maintainers flexibility for future licensing decisions.

License

Pad is licensed under Apache 2.0. By contributing, your code is released under the same license.