SurfSense/CONTRIBUTING.md

Contributing to SurfSense

Hey! 👋 Thanks for checking out SurfSense. We're stoked that you're interested in helping improve the project. Whether it's fixing bugs, suggesting features, improving docs, or just joining the conversation — every bit helps.

🧠 Before You Start

Join Our Discord
Want to stay in the loop, ask questions, or get feedback before starting something?
Hop into the official SurfSense community:
👉 https://discord.gg/ejRNvftDp9

That's where the latest updates, internal discussions, and collaborations happen.

📌 What Can You Work On?

There are 3 main ways to contribute:

✅ 1. Pick From the Roadmap

We maintain a public roadmap with well-scoped issues and features you can work on:
🔗 SurfSense GitHub Project Roadmap

💡 Tip: Look for tasks in Backlog or Ready status.

💡 2. Propose Something New

Have an idea that's not on the roadmap?

1. First, check for an existing issue
2. If it doesn't exist, create a new issue explaining your feature or enhancement
3. Wait for feedback from maintainers
4. Once approved, you're welcome to start working on a PR!

🐞 3. Report Bugs or Fix Them

Found a bug? Create an issue with:

• Steps to reproduce the issue
• Expected vs actual behavior
• Environment details (OS, browser, version)
• Any relevant logs or screenshots

Want to fix it? Go for it! Just link the issue in your PR.

🛠️ Development Setup

Prerequisites

• Docker & Docker Compose (recommended) OR manual setup
• Node.js (v18+ for web frontend)
• Python (v3.11+ for backend)
• PostgreSQL with PGVector extension
• API Keys for external services you're testing

Quick Start

1. Clone the repository

   git clone https://github.com/MODSetter/SurfSense.git
   cd SurfSense
   

2. Choose your setup method:

   • Docker Setup: Follow the Docker Setup Guide
   • Manual Setup: Follow the Installation Guide

3. Configure services:

   • Set up PGVector & PostgreSQL
   • Configure a file ETL service: Unstructured.io or LlamaIndex
   • Add API keys for external services

For detailed setup instructions, refer to our Installation Guide.

🏗️ Project Structure

SurfSense consists of three main components:

• surfsense_backend/ - Python/FastAPI backend service
• surfsense_web/ - Next.js web application
• surfsense_browser_extension/ - Browser extension for data collection

🧪 Development Guidelines

Code Quality & Pre-commit Hooks

We use pre-commit hooks to maintain code quality, security, and consistency across the codebase. Before you start developing:

1. Install and set up pre-commit hooks - See our detailed Pre-commit Guide
2. Understand the automated checks that will run on your code
3. Learn about bypassing hooks when necessary (use sparingly!)

Code Style

• Backend: Follow Python PEP 8 style guidelines
• Frontend: Use TypeScript and follow the existing code patterns
• Formatting: Use the project's configured formatters (Black for Python, Prettier for TypeScript)

Commit Messages

Use clear, descriptive commit messages:

feat: add document search functionality
fix: resolve pagination issue in chat history
docs: update installation guide
refactor: improve error handling in connectors

Testing

• Write tests for new features and bug fixes
• Ensure existing tests pass before submitting
• Include integration tests for API endpoints

Branch Naming

Use descriptive branch names:

• feature/add-document-search
• fix/pagination-issue
• docs/update-contributing-guide

🔄 Pull Request Process

Before Submitting

1. Create an issue first (unless it's a minor fix)
2. Fork the repository and create a feature branch
3. Make your changes following the coding guidelines
4. Test your changes thoroughly
5. Update documentation if needed

PR Requirements

• One feature or fix per PR - keep changes focused
• Link related issues in the PR description
• Include screenshots or demos for UI changes
• Write descriptive PR title and description
• Ensure CI passes before requesting review

🔍 Code Review Process

1. Automated checks must pass (CI/CD pipeline)
2. At least one maintainer will review your PR
3. Address feedback promptly and professionally
4. Squash commits if requested to keep history clean
5. Celebrate when your PR gets merged! 🎉

📚 Documentation

When contributing, please:

• Update relevant documentation for new features
• Add or update code comments for complex logic
• Update API documentation for backend changes
• Add examples for new functionality

🆘 Getting Help

Stuck? Need clarification? Here's how to get help:

1. Check existing issues - your question might already be answered
2. Search the docs - https://www.surfsense.net/docs/
3. Ask in Discord - https://discord.gg/ejRNvftDp9
4. Create an issue - if it's a bug or feature request

⭐ Other Ways to Contribute

Not ready to code? You can still help!

• Give us a star ⭐ on GitHub
• Share SurfSense with your community
• Provide feedback on Discord
• Help triage issues and validate bug reports
• Improve documentation and examples
• Write tutorials or blog posts about SurfSense

🎯 Recognition

We appreciate all contributions! Contributors will be:

• Acknowledged in release notes
• Listed in our contributors section
• Invited to join our contributors' Discord channel
• Eligible for special contributor badges

📄 License

By contributing to SurfSense, you agree that your contributions will be licensed under the same license as the project.

---

Thank you for contributing to SurfSense! 🚀
Together, we're building something awesome.