Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
194 lines (131 loc) · 5.72 KB

CONTRIBUTING.md

File metadata and controls

194 lines (131 loc) · 5.72 KB
Raw

Contributing to FounderOS

Thank you for your interest in contributing. This document explains the process for reporting issues, proposing features, and submitting pull requests.

Table of Contents

Code of Conduct

Be respectful and constructive. Contributions of any skill level are welcome. Harassment, personal attacks, or dismissive communication will not be tolerated.

Getting Started

  1. Fork the repository and clone your fork:
git clone https://github.com/<your-username>/founder-os.git
cd founder-os
  1. Install dependencies:
npm install
  1. Copy the environment file and fill in your own credentials:
cp .env.example .env.local

You will need your own InsForge project, OpenRouter API key, and Stripe test account to run the app locally. See the README Getting Started section for detailed instructions.

  1. Run the development server:
npm run dev

Development Workflow

  1. Create a branch from main for your work. Use a descriptive name:
feat/team-collaboration
fix/kpi-deduplication-edge-case
docs/update-stripe-setup
refactor/memory-context-builder
  1. Keep your branch up to date with main using rebase, not merge:
git fetch origin
git rebase origin/main
  1. Run the linter before committing:
npm run lint
  1. Build the project to catch TypeScript and Next.js errors:
npm run build

Commit Convention

We use Conventional Commits. Every commit message should follow this format:

<type>(<scope>): <short summary>

[optional body]

[optional footer]

Types:

Type When to use
feat A new feature
fix A bug fix
refactor Code change that neither fixes a bug nor adds a feature
docs Documentation only changes
style Formatting, missing semicolons, etc — no logic change
test Adding or updating tests
chore Build process, dependency updates, tooling
perf A performance improvement

Examples:

feat(ai): add retry logic to OpenRouter client
fix(stripe): handle past_due subscription status in webhook handler
refactor(memory): extract context window builder into dedicated module
docs(readme): add Stripe CLI setup instructions

Pull Request Process

  1. Open a PR against main using the pull request template.
  2. Fill in all sections of the template — motivation, change description, test plan.
  3. Ensure npm run lint and npm run build pass with zero errors.
  4. Link any relevant issues using GitHub's Fixes #<issue> keyword.
  5. Request a review. PRs require at least one approving review before merge.
  6. Do not merge your own PR.

PR size guidelines:

  • Prefer smaller, focused PRs over large omnibus changes.
  • If your change spans multiple unrelated concerns, split it into separate PRs.
  • UI changes should include screenshots or a screen recording in the PR description.

Style Guide

TypeScript

  • All new code must be TypeScript. No any unless absolutely necessary — use unknown and narrow.
  • Prefer explicit return types on exported functions and API route handlers.
  • Co-locate types with their consumers when they are not shared. Shared types live in src/types/database.ts.

React

  • Use function components exclusively.
  • Keep components focused. If a file exceeds ~200 lines, consider splitting it.
  • Client components are marked "use client" at the top. Server components are the default — do not add "use client" unless the component uses browser APIs, hooks, or event handlers.
  • Follow the existing pattern for data fetching: server components fetch via createInsForgeServerClient(), client components use the insforge singleton from src/lib/insforge/client.ts.

API Routes

  • Every API route must return typed JSON responses.
  • Authenticate and authorise before processing. Do not trust projectId from the request body without verifying that the authenticated user owns the project.
  • AI routes must call checkUsageLimit before calling OpenRouter and incrementAiUsage after a successful response.

Database

  • All new tables must have Row Level Security enabled with per-operation policies.
  • Add new tables and policies in a new timestamped migration file under migrations/.
  • Never write raw SQL in application code. Use the InsForge SDK's query builder.

Naming

  • Files: kebab-case.ts / kebab-case.tsx
  • Components: PascalCase
  • Functions and variables: camelCase
  • Database columns: snake_case
  • Environment variables: SCREAMING_SNAKE_CASE

Testing

Currently the project does not have an automated test suite. Contributions that add tests (unit, integration, or E2E via Playwright) are especially welcome.

For now, manually verify your changes by:

  1. Running the app locally (npm run dev).
  2. Exercising the specific feature you changed end-to-end.
  3. Checking that the TypeScript compiler and linter report no errors (npm run build && npm run lint).

Security

If you discover a security vulnerability, do not open a public GitHub issue. Email the maintainer directly at the address listed on their GitHub profile. Include a description of the vulnerability, steps to reproduce, and any proof-of-concept code. You will receive a response within 48 hours.

Responsible disclosure is appreciated and will be acknowledged in the release notes.