Developers Handbook

Welcome to the Open Library Handbook! This guide provides developers with the information needed to get started, understand the codebase, contribute effectively, and participate in the community.

TIP

New to Open Library? Start with Step 1 of the Getting Started flow.

Canonical Guides

Use these as the source of truth for contributor workflows:

• Setup and first contribution: Quick Start
• Git and PR workflow: Git Workflow
• Linting and CI checks: Pre-Commit Guide
• Running tests: Testing Guide
• Community norms and contribution standards: Contributing

Development Tools

Guides for the tools we use to build Open Library:

• Development Tools Overview - IDE setup, local dev configuration, and links to tool-specific guides

Getting Started

New to Open Library development? Follow this order:

1. Quick Start - environment setup and first PR
2. Git Workflow
3. Testing Guide
4. Pre-Commit Guide
5. Browse Good First Issues, a live in-docs list of open issues tagged for newcomers

Understanding the Codebase

Learn how the Open Library application is structured:

• Understand Infogami
• Trace the step-by-step Lifecycle of a Network Request
• Add a new Endpoint (Plugin Tutorial)
• Technical Tour & System Overview (1h video)

Contributing to the Front-end

Guidance for working on the user interface:

• HTML Templates:
  • Work with HTML Templates (Frontend Guide)
  • Template Rendering Guide (deep dive)
  • Jinja Templates Guide
  • Asynchronously load Template Partials
  • Internationalize (i18n) Templates
• CSS & JavaScript:
  • Work with and build CSS (Frontend Guide)
  • Work with and build JavaScript (Frontend Guide)
• Design Resources:
  • Refer to our Design Pattern Library
  • Explore the Figma Design System

Contributing to the Back-end

Information for server-side development:

• Local Environment:
  • See How the Local Docker Services Fit Together
• Data & Search:
  • Understand our Database Model (DDL)
  • Work with the Solr search engine
  • Work on the Import Pipeline
  • Write Librarian Bots
• APIs & Architecture:
  • Use or Write APIs
  • Diagram the Production Architecture

Managing Your Developer Environment

Tips for local development:

• Import production data into your local environment
• Create new users locally

Common Coding Recipes & Techniques

Quick references for frequent tasks:

• Lookup Common Recipes
  • Use cache
  • Work with cookies
  • Fetch data efficiently from the database

Participating in the Community

Get involved with other contributors:

• Request a Slack Invite
• Attend Weekly Community Calls (Tues @ 9:00 AM PT)
• Volunteer for a Fellowship
• Apply for Google Summer of Code (GSoC)

Specific Feature Developer Guides

Video walkthroughs and documents for key areas:

• BookWorm / Affiliate Server Guide
• Developing the My Books & Reading Log (Video)
• Developing the Books Page (Video)
• Understanding the "Read" Button Logic (Video)

Project & Team Resources

High-level project management and related team portals:

Project Management

1. Directory of Projects
2. Important Documents by Year
3. Responsibilities Matrix