Contribution Guidelines for open-notebook: Issue-First Workflow and Development Standards

Contributions to open-notebook require an issue-first workflow where you must open an issue, propose a solution, and wait for maintainer assignment before writing any code—pull requests without approved issues are likely to be closed.

The open-notebook repository (lfnovo/open-notebook) welcomes developers of all experience levels but strictly enforces an issue-first workflow to protect contributors from wasted effort and ensure alignment with the project's architectural vision. Before submitting code, you must follow the structured process documented in docs/7-DEVELOPMENT/contributing.md and the top-level CONTRIBUTING.md file. This guide covers the mandatory workflow, branch naming conventions, testing requirements, and key files you will interact with when contributing.

Issue-First Workflow Requirements

The project maintains a strict issue-first workflow to prevent duplicate work and ensure architectural consistency. According to the source code documentation, you must complete three steps before coding begins.

Creating and Assigning Issues

First, open an issue using the provided templates (bug report or feature request) via the GitHub New Issue button. In the issue description, outline your proposed solution, affected components, and any architectural considerations. A maintainer will review your proposal and assign the issue to you only after the approach is approved. Pull requests submitted without an associated, approved issue are likely to be closed, as this protects the codebase from unvetted changes.

Feature Branch Workflow

Once assigned, follow the feature branch workflow described in docs/7-DEVELOPMENT/contributing.md:

# Fork the repository on GitHub, then clone your fork

git clone https://github.com/<your-username>/open-notebook.git
cd open-notebook

# Create a feature branch following naming conventions

git checkout -b feature/your-feature-name

Branch Naming Conventions

Type	Prefix	Example
Feature	feature/	feature/add-search-filter
Bug fix	fix/	fix/missing-metadata
Documentation	docs/	docs/update-readme

Commit Message Standards

Use present tense and imperative mood (e.g., Add feature, not Added feature). Keep the subject line under 72 characters and reference the issue number in the body when applicable.

Development Environment Setup

The project uses uv for dependency management and Ruff for linting and formatting. Set up your local environment before making changes:

# Install dependencies in a virtual environment

uv sync

# Run the test suite

uv run pytest

# Lint and format code

uv run ruff check .
uv run ruff format .

All contributions must include appropriate tests in the tests/ directory and pass the existing pytest suite.

Code Standards and Architecture

Before writing code, review the architectural documentation to understand the system design. The backend uses FastAPI, with routers registered in api/main.py and core utilities located in open_notebook/utils/.

Adding New API Endpoints

When adding FastAPI endpoints, create a new router file and register it in the main application:

# api/routers/example.py

from fastapi import APIRouter

router = APIRouter()

@router.get("/hello")
async def hello() -> dict:
    return {"message": "Hello, Open Notebook!"}

Then register the router in api/main.py:

from .routers import example

app.include_router(example.router, prefix="/api")

Updating Documentation

If your changes affect public APIs or user-facing functionality, update the corresponding markdown files in docs/. For example, architectural changes require updates to docs/7-DEVELOPMENT/architecture.md, while code style changes may require updates to docs/7-DEVELOPMENT/code-standards.md.

Essential Files for Contributors

Path	Purpose
CONTRIBUTING.md	Top-level entry point that redirects to the full contribution guide
docs/7-DEVELOPMENT/contributing.md	Complete workflow documentation, issue-first process, and branch strategy
docs/7-DEVELOPMENT/architecture.md	High-level system architecture (backend, frontend, database)
docs/7-DEVELOPMENT/design-principles.md	Project philosophy and guiding values
docs/7-DEVELOPMENT/code-standards.md	Language-specific conventions for Python and TypeScript
api/main.py	FastAPI entry point for router registration
open_notebook/utils/	Core utilities (embedding, chunking, encryption)
tests/	pytest suite covering API, graphs, and models

Summary

• Issue-first workflow is mandatory: Open an issue, propose a solution, and wait for maintainer assignment before coding.
• Use uv for dependency management: Run uv sync to install dependencies and uv run pytest to test.
• Follow branch naming conventions: Use feature/, fix/, or docs/ prefixes with descriptive names.
• Write commit messages in present tense: Use imperative mood and keep subject lines under 72 characters.
• Update relevant documentation: Changes to api/main.py or open_notebook/utils/ require corresponding documentation updates.

Frequently Asked Questions

What happens if I submit a pull request without an approved issue?

Pull requests submitted without an associated, approved issue are likely to be closed. This policy protects contributors from spending effort on work that may not align with the project's architectural vision or design principles.

How do I set up the development environment for open-notebook?

Install uv (the Python package manager), then run uv sync to install dependencies in a virtual environment. Use uv run pytest to execute tests and uv run ruff check . followed by uv run ruff format . to lint and format your code.

Where can I find the complete contribution guidelines?

The full contribution guide lives in docs/7-DEVELOPMENT/contributing.md, which is also linked from the top-level CONTRIBUTING.md file. Additionally, review docs/7-DEVELOPMENT/architecture.md and docs/7-DEVELOPMENT/code-standards.md before making changes.

How do I get help if I have questions about contributing?

Join the community Discord at https://discord.gg/37XJPXfz2w for real-time discussion, or use GitHub Discussions for longer-form questions. Always use the issue templates when reporting bugs or requesting features.

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