The Typical Workflow for Making Changes and Submitting Them to lfnovo/open-notebook

Open Notebook follows an issue-first, feature-branch workflow that requires creating an issue before coding, using descriptive branch names, and running tests and linters before submitting pull requests.

The lfnovo/open-notebook repository maintains a strict contribution protocol to ensure code quality and architectural alignment within its three-tier stack (React frontend, Python API, SurrealDB backend). Understanding the typical workflow for making changes and submitting them to lfnovo/open-notebook helps contributors avoid rejected pull requests and streamlines the review process.

Prerequisites: Create and Assign an Issue

Before writing any code, you must open an issue describing the bug or feature you intend to address. Explain the problem, propose a solution, and request assignment from the maintainers.

According to the contribution policy in docs/7-DEVELOPMENT/contributing.md, pull requests that lack an assigned issue may be closed immediately. This requirement prevents duplicate work and guarantees that new features align with the project's architecture.

Once a maintainer reviews and approves your proposal, they will assign the issue to you. Only then should you begin development.

Fork and Branch Strategy

After receiving assignment, fork the repository on GitHub and create a feature branch using the project's naming conventions.

Use feature/<description> for new functionality or fix/<description> for bug repairs:

git checkout -b feature/add-pdf-ingestion

This naming convention appears throughout the maintainer guidelines and helps reviewers categorize incoming changes.

Configure Your Development Environment

Set up your local environment by installing dependencies and starting the required services. The project uses SurrealDB as its database layer and requires specific environment configurations.

Follow the quick-start guide in the documentation to initialize the API locally. Key entry points for development include:

• Backend services: open_notebook/api/sources_service.py and other modules under open_notebook/
• Frontend components: React/Next.js files in frontend/pages/**/*.tsx

Ensure your environment matches the specifications in CONFIGURATION.md before proceeding.

Implement and Test Your Changes

Make your edits to the relevant source files, then validate them against the test suite and linting rules.

Run the following commands from the repository root:

uv run pytest               # execute unit and integration tests

uv run ruff check .         # lint the codebase

uv run ruff format .        # auto-format

The contribution guide explicitly requires these checks to pass before submission. Update or add tests in tests/**/test_*.py to cover any new functionality you introduce.

Submit a Pull Request

Commit your changes using the project's commit style: imperative mood with a maximum of 72 characters.

git add .
git commit -m "feat: add PDF ingestion workflow"

Push the branch to your fork and open a Pull Request on GitHub:

git push origin feature/add-pdf-ingestion

In your PR description, you must:

• Reference the issue number using Fixes #123
• Summarize what changed and why
• Attach screenshots for UI modifications
• Complete the entire PR template as defined in the repository guidelines

Maintainers will review your code, leave comments, and may request changes. Address feedback promptly and push additional commits to the same branch.

Sync Your Fork After Merge

Once your PR is approved and merged into main, synchronize your fork to prepare for future contributions.

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

This step ensures your local copy reflects the latest codebase and prevents divergence in subsequent contributions.

Summary

• Issue-first requirement: Create and get assigned an issue before coding to avoid PR rejection
• Branch naming: Use feature/<description> or fix/<description> format
• Quality gates: Run uv run pytest, uv run ruff check ., and uv run ruff format . before submitting
• PR requirements: Reference the issue number, fill the template completely, and use imperative commit messages under 72 characters
• Repository structure: Backend logic lives in open_notebook/, frontend in frontend/, and contribution rules in docs/7-DEVELOPMENT/contributing.md

Frequently Asked Questions

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

According to the lfnovo/open-notebook contribution policy, maintainers may close pull requests that lack an associated assigned issue. This rule prevents duplicate work and ensures architectural alignment before development begins.

Which files should I edit when adding new content ingestion capabilities?

For backend changes, modify services under open_notebook/ such as open_notebook/api/sources_service.py. For frontend modifications, edit the React components in frontend/pages/**/*.tsx. Always update corresponding tests in tests/**/test_*.py.

What commit message format does Open Notebook require?

Use the imperative mood and limit your subject line to 72 characters. For example: feat: add PDF ingestion workflow or fix: resolve database connection timeout. This format appears in the project guidelines and maintains consistency across the git history.

How do I keep my fork synchronized after my pull request is merged?

Fetch from the upstream repository, checkout your local main branch, merge the upstream changes, and push to your fork. The specific commands are git fetch upstream, git checkout main, git merge upstream/main, and git push origin main. This prevents branch divergence and simplifies future contributions.

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