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

> Learn open-notebook contribution guidelines. Follow the issue-first workflow: open an issue, propose a solution, and get maintainer assignment before coding. Unapproved PRs may be closed.

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

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/contributing.md) and the top-level [`CONTRIBUTING.md`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/contributing.md):

```bash

# 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:

```bash

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

```python

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

```python
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`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/architecture.md), while code style changes may require updates to [`docs/7-DEVELOPMENT/code-standards.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/code-standards.md).

## Essential Files for Contributors

| Path | Purpose |
|------|---------|
| [`CONTRIBUTING.md`](https://github.com/lfnovo/open-notebook/blob/main/CONTRIBUTING.md) | Top-level entry point that redirects to the full contribution guide |
| [`docs/7-DEVELOPMENT/contributing.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/contributing.md) | Complete workflow documentation, issue-first process, and branch strategy |
| [`docs/7-DEVELOPMENT/architecture.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/architecture.md) | High-level system architecture (backend, frontend, database) |
| [`docs/7-DEVELOPMENT/design-principles.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/design-principles.md) | Project philosophy and guiding values |
| [`docs/7-DEVELOPMENT/code-standards.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/code-standards.md) | Language-specific conventions for Python and TypeScript |
| [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/contributing.md), which is also linked from the top-level [`CONTRIBUTING.md`](https://github.com/lfnovo/open-notebook/blob/main/CONTRIBUTING.md) file. Additionally, review [`docs/7-DEVELOPMENT/architecture.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/architecture.md) and [`docs/7-DEVELOPMENT/code-standards.md`](https://github.com/lfnovo/open-notebook/blob/main/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.