# The Typical Workflow for Making Changes and Submitting Them to lfnovo/open-notebook > Learn the typical workflow for submitting changes to lfnovo/open-notebook. Discover the issue-first, feature-branch process including creating issues, descriptive branch names, and testing before submitting pull requests. - Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook) - Tags: how-to-guide - Published: 2026-06-26 --- **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`](https://github.com/lfnovo/open-notebook/blob/main/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/` for new functionality or `fix/` for bug repairs: ```bash 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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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: ```bash 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. ```bash git add . git commit -m "feat: add PDF ingestion workflow" ``` Push the branch to your fork and open a Pull Request on GitHub: ```bash 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. ```bash 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/` or `fix/` 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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.