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

> Learn the open-notebook development workflow. Follow issue first contribution steps including assignment, feature branching, testing, and conventional commits for seamless code integration.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-13

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/development-setup.md), while the FastAPI entry point resides in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py).

```bash

# 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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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:

```bash
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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) and requires the `uv` package manager for dependency synchronization and environment management.