Development Workflow for Open Notebook: A Complete Contributor's Guide

Open Notebook follows a strict issue-first development workflow where contributors must create an issue, get assigned by a maintainer, develop on feature branches, and submit pull requests with tests and conventional commits.

Open Notebook is a privacy-first AI notebook application built with FastAPI, Next.js, and SurrealDB. If you want to contribute to the lfnovo/open-notebook repository, understanding the development workflow ensures your code aligns with the project's architectural vision and quality standards. The workflow is documented in docs/7-DEVELOPMENT/contributing.md and spans from issue creation to final merge.

The Issue-First Workflow

Creating and Claiming Issues

Every contribution starts with an issue. Before writing any code, create an issue describing the problem, desired outcome, and optional draft solution. A maintainer reviews the proposal to check for duplicates and assigns the issue to you. Only begin development after receiving assignment in the GitHub issue tracker.

Setting Up Your Development Environment

The project requires Python 3.11+, Docker for SurrealDB, and the uv package manager. The detailed setup instructions live in docs/7-DEVELOPMENT/development-setup.md, while the FastAPI entry point resides in api/main.py.

# Clone the repository

git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook

# Install Python dependencies using uv

uv sync

# Start the local SurrealDB container (Docker required)

docker compose up -d surrealdb

# Launch the API server on port 5055

uv run python -m uvicorn api.main:app --reload --port 5055

# Run the full test suite

uv run pytest

# Lint and format code

uv run ruff check .
uv run ruff format .

# Create a feature branch

git checkout -b feature/add-my-awesome-module
git add .
git commit -m "feat: add my awesome module"
git push origin feature/add-my-awesome-module

Understanding the Architecture

Open Notebook uses a three-layer architecture defined in docs/7-DEVELOPMENT/architecture.md. Contributors must respect these boundaries when implementing features.

• Frontend (frontend/): Next.js 16 with React 19, Zustand state management, and TanStack Query
• API Backend (api/ and open_notebook/): FastAPI with async-first design, LangGraph workflows in open_notebook/graphs/, and unified AI providers via the Esperanto library
• Database (open_notebook/database/): SurrealDB with async driver and automatic migrations handled in open_notebook/database/repository.py

Coding Standards and Quality Assurance

Testing Requirements

All new functionality requires unit or integration tests placed under the tests/ directory. Run the complete suite using uv run pytest as specified in docs/7-DEVELOPMENT/testing.md. The test suite covers API endpoints, graph workflows, utilities, and models.

Linting and Formatting

The project enforces code quality using ruff for both linting and auto-formatting. Execute these commands before submitting:

uv run ruff check .
uv run ruff format .

Commit Conventions

Write commit messages in imperative present tense (e.g., feat: add multi-speaker podcast support). The contributing guide in docs/7-DEVELOPMENT/contributing.md contains the full commit message specification.

Submitting Your Contribution

Branch Strategy

Create branches from main using the naming convention feature/<description> for new features or fix/<description> for bugs. The main branch always contains production-ready code, so never commit directly to it.

Pull Request Process

Push your branch and open a PR that references the original issue (Fixes #123) and includes:

• A concise description of what changed and why
• Test results or screenshots for UI changes
• Documentation updates if applicable

The PR review process is outlined in docs/7-DEVELOPMENT/contributing.md#pull-request-process. Address reviewer feedback through additional commits until a maintainer approves the merge.

Keeping Your Fork Synced

Regularly fetch upstream changes and rebase or merge them into your local main branch to avoid drift. The contributing guide provides specific instructions for maintaining fork synchronization.

Summary

• Create an issue and get assigned by a maintainer before writing any code
• Use feature/ or fix/ branches branched from the main branch
• Set up Python 3.11+, Docker, and SurrealDB locally using uv sync
• Respect the three-layer architecture: Frontend (Next.js), API (FastAPI/LangGraph), and Database (SurrealDB)
• Write tests in tests/ and verify with uv run pytest
• Lint and format using uv run ruff check . and uv run ruff format .
• Follow conventional commit message formatting
• Reference issues in PRs with Fixes #123 and include test results
• Sync your fork regularly to avoid divergence from upstream

Frequently Asked Questions

Do I need to create an issue before submitting a pull request?

Yes. Open Notebook requires an issue-first workflow documented in docs/7-DEVELOPMENT/contributing.md#issue-first-workflow. You must create an issue describing the problem and get assigned by a maintainer before writing code. This prevents duplicate work and ensures alignment with the project's privacy-first ethos and multi-provider AI architecture.

What branch naming convention should I use?

Use feature/<description> for new features and fix/<description> for bug fixes. Always branch from main, which contains production-ready code. The branch strategy details are specified in docs/7-DEVELOPMENT/contributing.md#branch-strategy.

How do I run tests locally?

Navigate to the project root and execute uv run pytest to run the full test suite. Tests are located in the tests/ directory and cover API endpoints, graph workflows, utilities, and models. Ensure all new functionality has corresponding test coverage as required by docs/7-DEVELOPMENT/testing.md.

What Python version is required for development?

Open Notebook requires Python 3.11 or higher. The project uses modern Python features including async/await patterns throughout the FastAPI backend in api/main.py and requires the uv package manager for dependency synchronization and environment management.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}