Rename CONTRIBUTION.md to CONTRIBUTING.md so GitHub surfaces it, add feature request and Resend compatibility gap templates, contact links for discussions and private advisories, and a security policy. Drop the upstream marketing template and point the bug template at mail.scribase.com. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.2 KiB
Contributing to Scribase Mail
Thanks for your interest in contributing to Scribase Mail! We’re an open-source email infrastructure platform, and we’d love your help to make it even better. This guide will walk you through how to get started, set up the project locally, and submit contributions.
Getting Started
All contributions begin with setting up the project locally. Follow the steps below to get started.
Refer to the full setup guide:
apps/docs/get-started/local.mdx
Prerequisites
You’ll need:
- A GitHub account
- Node.js v18+
pnpm(usecorepack enableto activate)- Docker (recommended)
- An Oracle Cloud account with Email Delivery (free tier is fine)
Setting Up the Project
1. Fork & Clone
git clone https://github.com/YOUR-USERNAME/scribase-mail-studio.git
cd scribase-mail-studio
2. Install Dependencies
corepack enable
pnpm install
3. Setup Environment Variables
cp .env.example .env
Then:
- Generate a secret:
openssl rand -base64 32
-
Add this to
.envasNEXTAUTH_SECRET. -
Create symlink for Next.js:
ln -s ../../.env apps/web/.env
Next.js requires the
.envfile in its directory. This symlink ensures both root andapps/webcan access the same environment variables.
4. GitHub OAuth (Optional for Dev)
Set up a GitHub OAuth App:
- Homepage:
http://localhost:3000/login - Callback:
http://localhost:3000/api/auth/callback/github
Add credentials to .env:
GITHUB_ID=your_client_id
GITHUB_SECRET=your_client_secret
5. Oracle Cloud Email Delivery (Optional for local email)
If you want to send real emails, add your OCI SMTP credentials and API key:
SMTP_HOST=smtp.email.eu-frankfurt-1.oci.oraclecloud.com
SMTP_USER=your_smtp_user
SMTP_PASS=your_smtp_password
OCI_TENANCY=ocid1.tenancy...
OCI_USER=ocid1.user...
OCI_FINGERPRINT=aa:bb:...
OCI_PRIVATE_KEY_PATH=/path/to/oci_api_key.pem
Without them the app runs; sends fail at the provider step.
Running the App
Option 1: Docker (Recommended)
pnpm d
- Dashboard: http://localhost:3000
- Marketing Site: http://localhost:3001
To test GitHub login, run:
cloudflared tunnel --url http://localhost:3000
Paste the Cloudflare URL in your GitHub App callback settings.
Option 2: Manual DB Setup
If you're using your own PostgreSQL & Redis:
- Add in
.env:
DATABASE_URL=your_postgres_url
REDIS_URL=your_redis_url
- Migrate database:
pnpm db:migrate-dev
- Start dev server:
pnpm dev
- Use
cloudflaredas mentioned above if needed.
Run Documentation Locally
pnpm dev:docs
Code Structure Overview
apps/
├── web # Dashboard & Email Infra
├── marketing # Landing page
├── docs # This documentation site
packages/
├── eslint-config # Shared ESLint rules
├── sdk # TypeScript SDK for Scribase Mail REST API
├── tailwind-config # Shared Tailwind setup
├── typescript-config # Shared tsconfig
├── ui # Shared UI components (buttons, modals, etc.)
Making Contributions
- Create a Feature Branch
git checkout -b feat/your-feature
-
Make Your Changes
- Follow the existing project structure.
- Write clean, modular, and reusable code.
- Formatting is enforced with Prettier.
-
Commit Your Work
git add .
git commit -m "feat: your message here"
- Push and Open a Pull Request
git push origin feat/your-feature
- Open a PR against the
mainbranch - Fill in the PR template
Community and Support
- GitHub Discussions: Start a discussion
- GitHub Issues: Report issues or bugs
Questions?
Need help or unsure where to begin? Just ask!
- Open an Issue
We’re excited to see your ideas and contributions!