Contributing to PostHog

​

Getting Started

# Create a feature branch
git checkout -b your-feature-name

# Make your changes
# ...

# Commit with conventional commits
git commit -m "feat: add new feature"

​

Commit Message Convention

​

Format

<type>(<scope>): <description>

​

Commit Types

feat: add session replay export
feat(feature-flags): implement multivariate flags
feat(llma): add token usage tracking

fix: resolve infinite loop in query runner
fix(cohorts): handle empty cohort in query builder
fix(replay): prevent memory leak in player

chore: update dependency versions
chore(ci): optimize GitHub Actions workflow
chore: update AGENTS.md instructions
chore(tests): add coverage for edge cases

​

Scope Convention

feat(feature-flags): ...
fix(experiments): ...
feat(session-replay): ...

feat(llma): ...      # LLM analytics
chore(ci): ...       # CI/CD
chore(docs): ...     # Documentation

​

Rules

• Scope is optional but encouraged
• Description must be lowercase
• No period at the end
• Keep first line under 72 characters

feat(insights): add retention graph export
fix: handle null values in event properties
chore(ci): update GitHub Actions workflow

Add retention graph export  # Missing type
Feat(Insights): Add retention graph export.  # Wrong case, has period
feat add export  # Missing colon

​

Creating a Pull Request

​

Before Submitting

# Backend tests
pytest

# Frontend tests
pnpm --filter=@posthog/frontend test

# Product tests (if applicable)
pnpm turbo run backend:test --filter=@posthog/products-<name>

# Python
ruff check . --fix
ruff format .

# TypeScript
pnpm --filter=@posthog/frontend format
pnpm --filter=@posthog/frontend typescript:check

# Update your branch with latest main
git fetch origin
git rebase origin/master

# Resolve conflicts if any
# ...

# Force push (since you rebased)
git push --force-with-lease

​

PR Description

## Changes

- Added retention graph export functionality
- Updated API serializer to include export options
- Added frontend UI for export button

## Testing

- [ ] Added unit tests for export logic
- [ ] Tested export with large datasets
- [ ] Verified CSV format is correct

## Related Issues

Closes #12345

​

PR Checklist

• ✅ Tests pass locally
• ✅ Code is formatted (ruff/oxfmt)
• ✅ No merge conflicts
• ✅ Conventional commit format
• ✅ Added tests for new functionality
• ✅ Updated docs if needed
• ✅ Followed existing patterns

​

Review Process

​

What to Expect

• Initial acknowledgement: Few days to 2 weeks
• Full review: Depends on complexity and support load
• Merge: After approval and CI passes

​

Before Full Review

• Tests pass locally and merge conflicts are resolved
• You’ve responded to automated review feedback (e.g., Greptile comments)
• The change is focused and includes tests where appropriate
• You’ve followed existing patterns and conventions

​

Review Outcomes

​

Contribution Guidelines

​

Code Style

# Use type hints
def create_feature_flag(
    team_id: int,
    key: str,
    enabled: bool,
) -> FeatureFlag:
    ...

# Use descriptive names
user_feature_flags = get_flags_for_user(user_id)

# Early returns over nesting
if not user:
    return None

if not user.is_active:
    return None

return user.feature_flags

// Explicit return types
function getFeatureFlags(): FeatureFlag[] {
    // ...
}

// Use Kea for business logic, avoid React hooks
export const featureFlagsLogic = kea<featureFlagsLogicType>({
    // Logic here
})

// Tailwind classes instead of inline styles
<div className="flex items-center gap-2">

​

Architecture Guidelines

• New features → Create in products/ directory
• API views → Declare request/response schemas with @validated_request or @extend_schema
• Team filtering → Always filter querysets by team_id
• Team extensions → Don’t add domain fields to Team model, use extension pattern

​

Testing Requirements

• Add tests for new functionality
• Prefer parameterized tests over multiple assertions
• Test team isolation for security
• No doc comments in Python tests
• Single top-level describe block in Jest tests

​

Security

# ✅ Parameterized queries
cursor.execute("SELECT * FROM table WHERE id = %s", [id])

# ❌ Never use f-strings with user input
cursor.execute(f"SELECT * FROM table WHERE id = {id}")  # SQL injection!

# ✅ User provides entire expression (parser validates)
parse_expr(self.query.expression)

# ✅ User data in placeholders
parse_expr("{x}", placeholders={"x": ast.Constant(value=user_input)})

# ❌ User data interpolated into template
parse_expr(f"field = '{self.query.value}'")  # Can escape context!

​

Working with Products

​

Creating a New Product

# Bootstrap product structure
bin/hogli product:bootstrap your_product_name

# This creates:
# - products/your_product_name/backend/
# - products/your_product_name/frontend/
# - manifest.tsx
# - package.json

1. Register in posthog/settings/web.py under PRODUCTS_APPS
2. Update tach.toml with import boundaries
3. Add API routes in posthog/api/__init__.py
4. Verify with bin/hogli product:lint your_product_name

​

Migrations

# Create migration
python manage.py makemigrations your_product_name

# Apply locally
python manage.py migrate

# Create migration
python manage.py create_clickhouse_migration migration_name

# Apply locally
python manage.py migrate_clickhouse

​

Paid Features

​

Getting Help

​

Additional Resources

• Monorepo Structure - Understanding the codebase layout
• Development Setup - Local environment setup
• Testing Guide - How to write and run tests
• Developing Locally - Full handbook guide

​

Thank You