Contributing
Set up local development, understand the codebase, run tests, write docs, and follow security disclosure rules.
Before contributing
BaseBuddy is built around one rule: it edits existing schemas through saved mappings. Contributions should preserve that model.
Avoid changes that make BaseBuddy silently reshape user tables, coerce storage formats on save, or write content outside the dirty fields or explicit workflow actions.
The product model is summarized in Core concepts, Safe editing model, and Storage contract and UI.
Local development
Install dependencies and start the app:
shpnpm install
pnpm devThe app runs on port 8080.
Use onboarding or pnpm basebuddy setup to create basebuddy-data/basebuddy.config.json, then run readiness checks.
Installation and First-run setup are the public setup references contributors should keep aligned with app behavior.
Useful commands
| Command | Purpose |
|---|---|
pnpm setup:check | Check self-host setup readiness |
pnpm test | Run unit tests |
pnpm test:e2e | Run Playwright tests |
pnpm build | Build the app |
pnpm dev:playwright | Run the Playwright dev server on port 3100 |
Codebase map
| Area | Path |
|---|---|
| Editor shell | src/components/editor/project-editor.tsx |
| Content API route | src/app/api/projects/[projectId]/content/route.ts |
| Runtime orchestrator | src/lib/content-runtime/server.ts |
| Mapping model | src/lib/content-runtime/mapping.ts |
| Adapter layer | src/lib/content-runtime/adapter/* |
| Permissions and app state | src/lib/control-plane/* |
| Setup checker | scripts/check-self-host-setup.ts |
Documentation style
Write docs for someone trying to get something done. Explain the concept first, then the steps, then common blockers and how to verify.
Avoid vague lines like "use diagnostics after changes." Instead, explain when to use diagnostics, what it checks, what failure means, and what to do next.
Security disclosures
Don't open public issues with secrets, private content, exploitable proof details, or full database URLs. Follow SECURITY.md for vulnerability reports.
License and commercial terms
Check the repository LICENSE and any commercial terms file included with the distribution before using BaseBuddy in a product, service, or redistribution.
When changing docs, avoid making legal promises in prose. Link to the license files and keep the docs focused on product behavior.
Security covers responsible disclosure and redaction expectations for public examples.