vrr/SurfSense
2
0
Fork 0
mirror of https://github.com/MODSetter/SurfSense.git synced 2026-10-19 07:34:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: make first contributions match one tree, not the old hosted stack

Browse source 
Replace the Docker-first contributing guide with a short index, current Covenant 3.0, private security reports, and issue forms that name the four products.
This commit is contained in:
CREDO23 2026-09-18 00:58:33 +02:00
parent 20293586bf
commit 48a97bea68
12 changed files with 302 additions and 567 deletions
Download patch file Download diff file Expand all files Collapse all files

70
.github/ISSUE_TEMPLATE/README.md vendored
View file

@ -1,70 +0,0 @@
# Issue Templates Guide
Thank you for contributing to SurfSense! To help us address your issue efficiently, please follow these guidelines:
## 📝 Choosing the Right Template
- **🐛 Bug Report**: Use this when you encounter unexpected behavior, errors, or crashes
- **✨ Feature Request**: Use this to suggest new features or enhancements
- **📚 Documentation Issue**: Use this to report problems with documentation
## 🏷️ Required Labels/Tags
When creating an issue, please add appropriate labels:
### Deployment Type (Required)
Always specify where you encountered the issue:
- `cloud` - For issues on SurfSense Cloud (hosted version)
- `self-hosted` - For issues on self-hosted installations
### Priority (Optional but Recommended)
- `critical` - System crashes, data loss, security issues
- `high` - Major functionality broken
- `medium` - Feature partially works or has workarounds
- `low` - Minor issues, cosmetic problems
### Component (Optional)
Help us route your issue faster:
- `backend` - Python/FastAPI backend issues
- `frontend` - Web interface issues
- `extension` - Browser extension issues
- `database` - Database-related issues
- `api` - API endpoint issues
- `ui/ux` - User interface/experience issues
## ✅ Before Creating an Issue
1. **Search existing issues** - Your issue might already be reported
2. **Check documentation** - The answer might be in our docs
3. **Provide complete information** - Fill out all required fields in the template
4. **Be specific** - Include version numbers, error messages, and reproduction steps
## 💡 Tips for Quality Issues
### For Bug Reports
- Include screenshots or videos when possible
- Provide complete error messages and logs
- Specify exact steps to reproduce
- Include environment details (browser, OS, versions)
### For Feature Requests
- Explain the use case and benefits
- Describe the problem it solves
- Consider implementation challenges
## 🚀 Self-Hosted Users
If you're using a self-hosted version, please include:
- Installation method (Docker, manual, etc.)
- Python and Node.js versions
- Database type and version
- Any custom configuration
## 📞 Need Help?
- **Questions?** Use [GitHub Discussions](https://github.com/SurfSense/SurfSense/discussions)
- **Security Issues?** Please report privately to the maintainers
- **General Chat?** Join our community channels
Thank you for helping make SurfSense better! 🎉

57
.github/ISSUE_TEMPLATE/bug.yml vendored Normal file
View file

@ -0,0 +1,57 @@
name: Bug
description: Something is broken
title: "[bug] "
labels: [bug]
body:
- type: dropdown
id: area
attributes:
label: Area
options:
- Desktop app (surfsense_local)
- MCP (surfsense_mcp)
- Backend / scraper API (surfsense_backend)
- Web UI (surfsense_web)
- Docs / repo
- Unsure
validations:
required: true
- type: textarea
id: what
attributes:
label: What happened
validations:
required: true
- type: textarea
id: reproduce
attributes:
label: How to reproduce
placeholder: |
1.
2.
3.
validations:
required: true
- type: textarea
id: expected
attributes:
label: What you expected
validations:
required: true
- type: input
id: version
attributes:
label: Version
description: App version, git tag, or commit
- type: textarea
id: logs
attributes:
label: Logs
render: shell
- type: checkboxes
id: checks
attributes:
label: Checks
options:
- label: I searched existing issues
required: true

59
.github/ISSUE_TEMPLATE/bug_report.md vendored
View file

@ -1,59 +0,0 @@
---
name: Bug Report
about: Report a bug or unexpected behavior in SurfSense
title: '[BUG] '
labels: bug
assignees: ''
---
## Bug Description
<!-- Provide a clear and concise description of the bug -->
## Deployment Type
<!-- Please select where you encountered this issue -->
- [ ] SurfSense Cloud (hosted version)
- [ ] Self-hosted version
## Steps to Reproduce
<!-- Provide detailed steps to reproduce the behavior -->
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error
## Expected Behavior
<!-- Describe what you expected to happen -->
## Actual Behavior
<!-- Describe what actually happened -->
## Screenshots/Videos
<!-- If applicable, add screenshots or videos to help explain the problem -->
## Environment Information
<!-- Please complete the following information -->
- **Browser:** [e.g., Chrome 120, Firefox 121, Safari 17]
- **Operating System:** [e.g., Windows 11, macOS 14, Ubuntu 22.04]
- **SurfSense Version:** [e.g., v1.0.0 or commit hash if self-hosted]
### Additional Environment Details (for Self-hosted only)
<!-- If you selected self-hosted, please provide: -->
- **Python Version:** [e.g., 3.11]
- **Node.js Version:** [e.g., 20.10.0]
- **Database:** [e.g., PostgreSQL 15]
- **Deployment Method:** [e.g., Docker, Manual installation]
## Additional Context
<!-- Add any other context about the problem here -->
## Logs/Error Messages
<!-- If applicable, paste relevant logs or error messages -->
```
Paste logs here
```
## Checklist
- [ ] I have searched existing issues to ensure this is not a duplicate
- [ ] I have provided all the required information above
- [ ] I have added appropriate labels (bug, deployment type)

18
.github/ISSUE_TEMPLATE/config.yml vendored
View file

@ -1,11 +1,11 @@
blank_issues_enabled: true
blank_issues_enabled: false
contact_links:
- name: 📚 Documentation
url: https://www.surfsense.com/docs
about: Check our documentation for guides and setup instructions
- name: 💬 Discussions
- name: Discord
url: https://discord.gg/ejRNvftDp9
about: Questions and setup help
- name: Discussions
url: https://github.com/MODSetter/SurfSense/discussions
about: Ask questions and discuss ideas with the community
- name: 🤝 Contributing Guide
url: https://github.com/MODSetter/SurfSense/blob/main/CONTRIBUTING.md
about: Learn how to contribute to SurfSense
about: Ideas that are not a bug or a concrete feature yet
- name: Security advisory
url: https://github.com/MODSetter/SurfSense/security/advisories/new
about: Report a vulnerability privately. Do not open a public issue.

18
.github/ISSUE_TEMPLATE/docs.yml vendored Normal file
View file

@ -0,0 +1,18 @@
name: Docs
description: Wrong, missing, or unclear documentation
title: "[docs] "
labels: [documentation]
body:
- type: input
id: where
attributes:
label: Where
description: File path or URL
validations:
required: true
- type: textarea
id: what
attributes:
label: What should change
validations:
required: true

41
.github/ISSUE_TEMPLATE/documentation.md vendored
View file

@ -1,41 +0,0 @@
---
name: Documentation Issue
about: Report issues or suggest improvements for documentation
title: '[DOCS] '
labels: documentation
assignees: ''
---
## Documentation Issue
<!-- Describe the documentation issue or improvement needed -->
## Location
<!-- Where is the documentation issue? -->
- **File/Page:** [e.g., README.md, docs/setup.md]
- **Section:** [e.g., Installation, Configuration]
- **URL:** [if applicable]
## Issue Type
<!-- Select the type of documentation issue -->
- [ ] Outdated information
- [ ] Missing information
- [ ] Incorrect information
- [ ] Typo/Grammar
- [ ] Unclear explanation
- [ ] Missing example
- [ ] Other (specify below)
## Current State
<!-- Describe what the documentation currently says (if applicable) -->
## Suggested Improvement
<!-- Describe what you think should be changed or added -->
## Additional Context
<!-- Add any other context, screenshots, or examples here -->
## Checklist
- [ ] I have checked that this documentation issue doesn't already exist
- [ ] I have provided clear location information
- [ ] I have added appropriate labels (documentation)

41
.github/ISSUE_TEMPLATE/feature.yml vendored Normal file
View file

@ -0,0 +1,41 @@
name: Feature
description: Propose a change. Wait for a maintainer before writing a large PR.
title: "[feat] "
labels: [enhancement]
body:
- type: markdown
attributes:
value: New features need a maintainer to agree first. Bugs and docs do not.
- type: dropdown
id: area
attributes:
label: Area
options:
- Desktop app (surfsense_local)
- MCP (surfsense_mcp)
- Backend / scraper API (surfsense_backend)
- Web UI (surfsense_web)
- Docs / repo
- Unsure
validations:
required: true
- type: textarea
id: problem
attributes:
label: Problem
description: What is hard or missing today?
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposal
validations:
required: true
- type: checkboxes
id: checks
attributes:
label: Checks
options:
- label: I searched existing issues and discussions
required: true

52
.github/ISSUE_TEMPLATE/feature_request.md vendored
View file

@ -1,52 +0,0 @@
---
name: Feature Request
about: Suggest a new feature or enhancement for SurfSense
title: '[FEATURE] '
labels: enhancement
assignees: ''
---
## Feature Description
<!-- Provide a clear and concise description of the feature you'd like to see -->
## Target Deployment
<!-- Please select which deployment(s) this feature should apply to -->
- [ ] SurfSense Cloud (hosted version)
- [ ] Self-hosted version
- [ ] Both
## Problem Statement
<!-- Describe the problem or use case this feature would solve -->
<!-- Example: "I'm always frustrated when..." -->
## Proposed Solution
<!-- Describe how you envision this feature working -->
## Alternative Solutions
<!-- Describe any alternative solutions or features you've considered -->
## Benefits
<!-- Explain how this feature would benefit SurfSense users -->
-
-
## Use Case Examples
<!-- Provide concrete examples of how this feature would be used -->
1.
2.
## Additional Context
<!-- Add any other context, mockups, or screenshots about the feature request here -->
## Implementation Considerations
<!-- Optional: If you have technical insights, share them here -->
- [ ] This may require frontend changes
- [ ] This may require backend changes
- [ ] This may require database changes
- [ ] This may affect existing features
## Checklist
- [ ] I have searched existing issues/feature requests to ensure this is not a duplicate
- [ ] I have provided a clear description of the feature
- [ ] I have added appropriate labels (enhancement, deployment type)

44
.github/PULL_REQUEST_TEMPLATE.md vendored
View file

@ -1,41 +1,11 @@
<!--- Summarize your pull request in a few sentences -->
## What
## Description
<!--- Clearly describe what has changed in this pull request -->
## Why
## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->
<!--- If this PR relates to an open issue, please link to the issue here: FIX #123 -->
FIX #
Fixes #
## How I tested
## Screenshots
<!-- If applicable, add screenshots or images to demonstrate the changes visually -->
## API Changes
<!-- Document any API changes if applicable -->
- [ ] This PR includes API changes
## Change Type
<!--- Indicate what kind(s) of changes this PR includes: -->
- [ ] Bug fix
- [ ] New feature
- [ ] Performance improvement
- [ ] Refactoring
- [ ] Documentation
- [ ] Dependency/Build system
- [ ] Breaking change
- [ ] Other (specify):
## Testing Performed
<!--- Briefly describe how you have tested these changes and what verification was performed -->
- [ ] Tested locally
- [ ] Manual/QA verification
## Checklist
<!--- Please confirm the following by marking with an 'x' as appropriate -->
- [ ] Follows project coding standards and conventions
- [ ] Documentation updated as needed
- [ ] Dependencies updated as needed
- [ ] No lint/build errors or new warnings
- [ ] All relevant tests are passing
- [ ] This PR targets `dev`
- [ ] I ran the tests for the tree I touched
- [ ] No secrets or `.env` files

234
CODE_OF_CONDUCT.md
View file

@ -2,127 +2,161 @@
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to make our community welcoming, safe, and equitable for all.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
We are committed to fostering an environment that respects and promotes the
dignity, rights, and contributions of all individuals, regardless of
characteristics including race, ethnicity, caste, color, age, physical
characteristics, neurodiversity, disability, sex or gender, gender identity or
expression, sexual orientation, language, philosophy or religion, national or
social origin, socio-economic position, level of education, or other status.
The same privileges of participation are extended to everyone who participates
in good faith and in accordance with this Covenant.
## Our Standards
## Encouraged Behaviors
Examples of behavior that contributes to a positive environment for our
community include:
While acknowledging differences in social norms, we all strive to meet our
community's expectations for positive behavior. We also understand that our
words and actions may be interpreted differently than we intend based on
culture, background, or native language.
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
With these considerations in mind, we agree to behave mindfully toward each
other and act in ways that center our shared values, including:
Examples of unacceptable behavior include:
1. Respecting the purpose of our community, our activities, and our ways of
gathering.
2. Engaging kindly and honestly with others.
3. Respecting different viewpoints and experiences.
4. Taking responsibility for our actions and contributions.
5. Gracefully giving and accepting constructive feedback.
6. Committing to repairing harm when it occurs.
7. Behaving in other ways that promote and sustain the well-being of our
community.
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Restricted Behaviors
## Enforcement Responsibilities
We agree to restrict the following behaviors in our community. Instances,
threats, and promotion of these behaviors are violations of this Code of
Conduct.
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
1. Harassment. Violating explicitly expressed boundaries or engaging in
unnecessary personal attention after any clear request to stop.
2. Character attacks. Making insulting, demeaning, or pejorative comments
directed at a community member or group of people.
3. Stereotyping or discrimination. Characterizing anyone's personality or
behavior on the basis of immutable identities or traits.
4. Sexualization. Behaving in a way that would generally be considered
inappropriately intimate in the context or purpose of the community.
5. Violating confidentiality. Sharing or acting on someone's personal or
private information without their permission.
6. Endangerment. Causing, encouraging, or threatening violence or other harm
toward any person or group.
7. Behaving in other ways that threaten the well-being of our community.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
### Other Restrictions
1. Misleading identity. Impersonating someone else for any reason, or
pretending to be someone else to evade enforcement actions.
2. Failing to credit sources. Not properly crediting the sources of content
you contribute.
3. Promotional materials. Sharing marketing or other commercial content in a
way that is outside the norms of the community.
4. Irresponsible communication. Failing to responsibly present content which
includes, links or describes any other restricted behaviors.
## Reporting an Issue
Tensions can occur between community members even when they are trying their
best to collaborate. Not every conflict represents a code of conduct
violation, and this Code of Conduct reinforces encouraged behaviors and norms
that can help avoid conflicts and minimize harm.
When an incident does occur, it is important to report it promptly. Email
`rohan@surfsense.com`. Do not post reports in public GitHub issues or Discord
channels.
Community Moderators take reports of violations seriously and will make every
effort to respond in a timely manner. They will investigate all reports of
code of conduct violations, reviewing messages, logs, and recordings, or
interviewing witnesses and other participants. Community Moderators will keep
investigation and enforcement actions as transparent as possible while
prioritizing safety and confidentiality. In order to honor these values,
enforcement actions are carried out in private with the involved parties, but
communicating to the whole community may be part of a mutually agreed upon
resolution.
## Addressing and Repairing Harm
If an investigation by the Community Moderators finds that this Code of
Conduct has been violated, the following enforcement ladder may be used to
determine how best to repair harm, based on the incident's impact on the
individuals involved and the community as a whole. Depending on the severity
of a violation, lower rungs on the ladder may be skipped.
1. **Warning**
- Event: A violation involving a single incident or series of incidents.
- Consequence: A private, written warning from the Community Moderators.
- Repair: Examples of repair include a private written apology,
acknowledgement of responsibility, and seeking clarification on
expectations.
2. **Temporarily Limited Activities**
- Event: A repeated incidence of a violation that previously resulted in a
warning, or the first incidence of a more serious violation.
- Consequence: A private, written warning with a time-limited cooldown
period designed to underscore the seriousness of the situation and give
the community members involved time to process the incident. The cooldown
period may be limited to particular communication channels or
interactions with particular community members.
- Repair: Examples of repair may include making an apology, using the
cooldown period to reflect on actions and impact, and being thoughtful
about re-entering community spaces after the period is over.
3. **Temporary Suspension**
- Event: A pattern of repeated violation which the Community Moderators
have tried to address with warnings, or a single serious violation.
- Consequence: A private written warning with conditions for return from
suspension. In general, temporary suspensions give the person being
suspended time to reflect upon their behavior and possible corrective
actions.
- Repair: Examples of repair include respecting the spirit of the
suspension, meeting the specified conditions for return, and being
thoughtful about how to reintegrate with the community when the
suspension is lifted.
4. **Permanent Ban**
- Event: A pattern of repeated code of conduct violations that other steps
on the ladder have failed to resolve, or a violation so serious that the
Community Moderators determine there is no way to keep the community
safe with this person as a member.
- Consequence: Access to all community spaces, tools, and communication
channels is removed. In general, permanent bans should be rarely used,
should have strong reasoning behind them, and should only be resorted to
if working through other remedies has failed to change the behavior.
- Repair: There is no possible repair in cases of this severity.
This enforcement ladder is intended as a guideline. It does not limit the
ability of Community Moderators to use their discretion and judgment, in
keeping with the best interests of our community.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
rohan@surfsense.com.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
This Code of Conduct applies within all community spaces, and also applies
when an individual is officially representing the community in public or other
spaces. For SurfSense that includes GitHub (issues, PRs, discussions),
Discord, and official email or social accounts. Examples of representing our
community include using an official email address, posting via an official
social media account, or acting as an appointed representative at an online or
offline event.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
version 3.0, permanently available at
https://www.contributor-covenant.org/version/3/0/.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
For answers to common questions about Contributor Covenant, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.

226
CONTRIBUTING.md
View file

@ -1,212 +1,40 @@
# Contributing to SurfSense
# Contributing
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.
Bug fixes and docs are welcome without asking first. For a new feature, open an issue so we can agree it belongs here before you spend time on a large PR.
## 🧠 Before You Start
[`good first issue`](https://github.com/MODSetter/SurfSense/labels/good%20first%20issue) is a good place to start. It also helps to check [existing issues](https://github.com/MODSetter/SurfSense/issues) and [PRs](https://github.com/MODSetter/SurfSense/pulls).
**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](https://discord.gg/ejRNvftDp9)
Questions: [Discord](https://discord.gg/ejRNvftDp9) or [Discussions](https://github.com/MODSetter/SurfSense/discussions). Security: [SECURITY.md](SECURITY.md). Conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
That's where the *latest updates*, *internal discussions*, and *collaborations* happen.
## Getting set up
## 📌 What Can You Work On?
This repo holds four products. You can clone all of it, then only run the tree you are changing — that is usually enough for a first PR.
There are 3 main ways to contribute:
| Tree | Setup |
|------|--------|
| [`surfsense_local/`](surfsense_local/README.md) | Desktop app |
| [`surfsense_mcp/`](surfsense_mcp/README.md) | MCP server (often the lightest first PR) |
| `surfsense_backend/` | Scraper API / self-host backend |
| `surfsense_web/` | Self-host web UI (`pnpm`, not npm) |
### ✅ 1. Pick From the Roadmap
We maintain a public roadmap with well-scoped issues and features you can work on:
🔗 [SurfSense GitHub Project Roadmap](https://github.com/users/MODSetter/projects/2)
> 💡 **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.
## 🌿 Branching Workflow
We follow a **branch protection model** to keep `main` stable:
| Branch | Purpose | Who can merge |
|--------|---------|---------------|
| `main` | Stable/release branch | Maintainers only (from `dev`) |
| `dev` | Active development & integration | Via approved PRs from contributors |
| `feature/*`, `fix/*`, etc. | Individual work branches | Contributors create PRs to `dev` |
### Important Rules
- **All contributor PRs must target the `dev` branch.** PRs targeting `main` will not be accepted.
- `main` is updated exclusively by maintainers merging from `dev` when a release is ready.
- Always create your feature/fix branches from the latest `dev`.
## 🛠️ 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. **Fork and clone the repository**
```bash
git clone https://github.com/<your-username>/SurfSense.git
cd SurfSense
```
2. **Create your branch from `dev`**
```bash
git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name
```
3. **Choose your setup method**:
- **Docker Setup**: Follow the [Building from Source (Contributors)](https://www.surfsense.com/docs/legacy/docker-installation#building-from-source-contributors) section of the Docker Installation guide
- **Manual Setup**: Follow the [Installation Guide](https://www.surfsense.com/docs/legacy/)
4. **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](https://www.surfsense.com/docs/legacy/).
## 🏗️ Project Structure
SurfSense consists of:
- **`surfsense_backend/`** - Python/FastAPI backend service
- **`surfsense_web/`** - Next.js web application
- **`surfsense_local/`** - desktop app
- **`surfsense_mcp/`** - MCP server
## 🧪 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** - `pip install pre-commit && pre-commit install`
2. **Understand the automated checks** that will run on your code - every hook is listed in [`.pre-commit-config.yaml`](./.pre-commit-config.yaml); run them all with `pre-commit run --all-files`
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 (Ruff for Python, Biome 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
```bash
git clone https://github.com/<you>/SurfSense.git
cd SurfSense
git checkout dev
git checkout -b fix/short-name
```
### Testing
- Write tests for new features and bug fixes
- Ensure existing tests pass before submitting
- Include integration tests for API endpoints
### Branch Naming
Create branches from `dev` with descriptive 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 branch from `dev`
3. **Make your changes** following the coding guidelines
4. **Test your changes** thoroughly
5. **Update documentation** if needed
6. **Open a PR targeting the `dev` branch**
> **Note:** PRs targeting `main` will **not** be reviewed or merged. If you accidentally open a PR to `main`, please retarget it to `dev`.
### PR Requirements
- **Target the `dev` branch** — this is mandatory
- **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.com/docs/legacy/](https://www.surfsense.com/docs/legacy/)
3. **Ask in Discord** - [https://discord.gg/ejRNvftDp9](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.
We merge through `dev`. Open your PR against that branch.
## Pull requests
Small, focused PRs are easier to review.
- Say what changed, why, and how you tried it.
- `Fixes #123` links the issue and closes it on merge.
- [Allow edits from maintainers](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) lets us help on the branch.
- New files follow [AGENTS.md](AGENTS.md). Existing packages do not need a layout rewrite unless that is the issue.
- `surfsense_backend/app/proprietary/` is Business Source License 1.1. Ask a maintainer before changing it.
- Keep `.env` and secrets out of the commit.
CI on the PR should be green. One maintainer review is enough to merge.

9
SECURITY.md Normal file
View file

@ -0,0 +1,9 @@
# Security
Do not file public issues for vulnerabilities.
Report them with [GitHub private vulnerability reporting](https://github.com/MODSetter/SurfSense/security/advisories/new). If that is unavailable, email `rohan@surfsense.com` (same address as [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)).
Include the tree (`surfsense_local`, `surfsense_backend`, `surfsense_web`, `surfsense_mcp`), a reproduction, and impact.
We will acknowledge the report and fix before any public disclosure.