Contributing Guide

Thank you for your interest in contributing to Postbase! This guide covers everything you need to know to contribute effectively.

Quick Start

# Fork and clone
git clone https://github.com/YOUR_USERNAME/postbase.git
cd postbase
 
# Install dependencies
pnpm install
 
# Create feature branch
git checkout -b feature/your-feature
 
# Start development
pnpm dev

Development Setup

Prerequisites

Node.js 20 or later
pnpm 9 or later
Docker Desktop for PostgreSQL
PostgreSQL client (optional)

Running Services

# Start all services
pnpm dev
 
# Run specific package
pnpm --filter @postbase/cli dev
pnpm --filter @postbase/admin dev
pnpm --filter @postbase/docs dev
pnpm --filter @postbase/web dev
 
# Run tests
pnpm test
 
# Build all
pnpm build

Project Structure

postbase/
├── packages/
│   ├── cli/            # CLI tool (@postbase/cli)
│   ├── admin/          # Admin UI (@postbase/admin)
│   ├── daemon/         # Background service (@postbase/daemon)
│   ├── sdk/            # TypeScript SDK (@postbase/sdk)
│   ├── cloud-api/      # Cloud API (@postbase/cloud-api)
│   ├── backup-service/ # Backup worker
│   ├── docs/           # Documentation (docs.postbase.sh)
│   └── web/            # Landing page (postbase.sh)
├── docs/               # Internal documentation
├── CONTRIBUTING.md     # Contribution guidelines
└── .cursorrules        # Project guidelines

Documentation Requirements

:::warning Documentation is Required All contributions MUST include appropriate documentation updates. PRs without documentation will not be merged. :::

Documentation Checklist

Before submitting a PR, update:

Change Type	Required Updates
New feature	README, docs site, roadmap
Bug fix	Troubleshooting (if user-facing)
API change	API reference, SDK docs
CLI change	CLI reference
Config change	Configuration docs
Breaking change	Migration guide, changelog

Files to Update

Package READMEs: packages/*/README.md
Docs Site: packages/docs/pages/
Roadmap: packages/docs/pages/reference/roadmap.mdx
Cursor Rules: .cursorrules (for major changes)

Preview Documentation

# Start docs dev server
pnpm --filter @postbase/docs dev
 
# Build to verify
pnpm --filter @postbase/docs build

Code Style

TypeScript Guidelines

// Use explicit types
function createDatabase(name: string): Promise<Database> {
  // ...
}
 
// Prefer type over interface
type DatabaseConfig = {
  name: string
  schema?: string
}
 
// Use const assertions
const ENVIRONMENTS = ['development', 'staging', 'production'] as const
type Environment = typeof ENVIRONMENTS[number]

Naming Conventions

Type	Convention	Example
Variables/Functions	camelCase	`createDatabase`
Types/Classes	PascalCase	`DatabaseConfig`
Constants	SCREAMING_SNAKE	`MAX_CONNECTIONS`
Files	kebab-case	`database-manager.ts`

Pull Request Process

Before Submitting

✅ Update documentation
✅ Run pnpm test
✅ Run pnpm lint
✅ Run pnpm build
✅ Test changes locally

PR Title Format

Use conventional commits:

feat(cli): add database branching
fix(sdk): handle connection timeout
docs(api): update PITR endpoints
chore: upgrade dependencies

PR Template

## Summary
Brief description of changes
 
## Changes
- Change 1
- Change 2
 
## Documentation
- [ ] Updated README
- [ ] Updated docs site
- [ ] Added to roadmap
 
## Testing
- [ ] Tests pass
- [ ] Manual testing done

Commit Messages

Follow Conventional Commits:

# Feature
git commit -m "feat(cli): add database branching command"
 
# Fix
git commit -m "fix(sdk): handle connection pool exhaustion"
 
# Documentation
git commit -m "docs(api): document PITR endpoints"
 
# Refactor
git commit -m "refactor(daemon): extract health check logic"

Commit Types

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation
`style`	Formatting
`refactor`	Code restructure
`perf`	Performance
`test`	Tests
`chore`	Maintenance

Getting Help

GitHub Issues: Bugs and features
GitHub Discussions: Questions
Email: contributors@postbase.sh

Thank You!

Every contribution makes Postbase better. We appreciate your time and effort!