3.5 KiB
Contributing to Puter Backend
Thanks for contributing. These rules aren't strictly enforced — but following them makes every PR easier. If anything's unclear, ping a core maintainer or open the PR and ask.
New to the backend? Start with doc/architecture.md.
1. Test it. Run it.
Run the affected code path end-to-end before opening a PR. "It builds" is not "it works."
Add tests for new behavior, endpoints, or bug fixes. If something's genuinely hard to test, say so in the PR.
2. Follow existing patterns
Match the shape of similar code already in the repo. doc/architecture.md is the source of truth for layers, wiring, and naming. If you think a pattern is wrong, raise it — don't quietly diverge.
In plain-JS files, typing is encouraged via JSDoc @type annotations using the TypeScript type system, with @typedef for shared shapes. Don't type API surfaces as unknown or untyped ...args unless the values are passed through transparently to an upstream layer that owns their type.
Reuse before adding. Search src/backend/util/, the owning layer, and extensions/ before writing a helper, cache, validator, serializer, or provider adapter, and extend what exists instead of adding a parallel copy; copies drift. Don't add base classes, interfaces, factories, or wrappers with a single implementation or caller.
Keep hot paths cheap. Batch instead of querying per row in a loop, bound every query, cache, and outbound call, and build static data once rather than per request. Persistence goes through the table's store so cache invalidation stays with the write.
3. Don't expose system or user information
Scan your diff for stray logs, debug routes, internal paths, secrets, tokens, or user data in errors/responses. When in doubt, return less. Flag any auth, permission, or data-export changes in the PR description.
For private security reports, see SECURITY.md.
4. AI-assisted code is fine — understood code is required
Don't commit code you couldn't have written, debugged, or defended yourself. Read the diff, run it, and be ready to explain it in review.
Agents miss code outside their context and re-implement it. Check the diff for new helpers that duplicate existing ones before opening the PR.
5. Adding or changing APIs
If you add or change a public API (an endpoint, driver method, or puter-js method), follow doc/contributing-apis.md — backward compatibility, developer docs, types, and tests all move in the same PR.
The same rule applies to limits: rate limits, concurrency caps, quotas, and allowances are published in src/docs/src/rate-limits-and-quotas.md, and a PR that changes one of those numbers updates that page in the same PR. A limit nobody published is a limit developers only discover as a service failure.
6. Boy Scout Rule — leave it 1% better
Fix the typo, the dead import, the missing test, the bit you had to read twice. Keep cleanup proportional to the change — no refactors riding along on bug fixes.
Opening a PR
- One thing per PR where possible.
- Describe what and why; the diff shows how.
- Mention how you tested user-visible changes.
- Drafts welcome.
Questions? Message a core maintainer. Welcome aboard.