Text of docs.openlibrary.org › developers › quick-start.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout.

Open the live page

Quick Start | Open Library Docs

Skip to content Quick Start ​ Estimated time: 45-90 minutes Difficulty: Beginner-friendly Prerequisites: Docker , Git , and pre-commit installed This guide takes you from installation to your first pull request. Each step links to a detailed guide. Open the detailed guide when you need more information. TIP Need help? Join our weekly community calls (Tues @ 9am PT) or request a Slack invite . Step 0: Get Oriented (~10 minutes) ​ Watch the Quick Public Tour of Open Library (10 min) to understand what you'll be contributing to.

Read our Code of Conduct . Step 1: Set Up Your Environment (~20-30 minutes) ​ Clone the repository ​ sh git clone git@github.com:YOUR_USERNAME/openlibrary.git cd openlibrary make git make git prepares the git submodules of this repository. IMPORTANT Use git@ (SSH), not https:// . If you cloned with HTTPS, fix it here . TIP Windows users: If you do not use a Linux VM, see Fix line endings, symlinks and git submodules before you build.

If you skip these steps, the containers may not start. Build and run ​ sh docker compose up -d # builds the images on first run; the first build takes 15-30 minutes Start hot-reload for CSS/JS in a new terminal: sh docker compose run --rm home npm run watch Open http://localhost:8080 . You see the Open Library homepage with "development version" in the banner. For full Docker setup details, troubleshooting, and OS-specific instructions, see the Docker Guide .

Step 2: Find a Good First Issue (~10 minutes) ​ Browse Good First Issues . The list is fetched live from GitHub. Before you start, read how to pick up a Good First Issue in the Contributing guide. Good First Issues don't need assignment, but you must comment on the issue before opening your PR. Step 3: Create a Branch (~5 minutes) ​ Use the issue number from Step 2 in your branch name: sh git switch master git pull upstream master git switch -c 123/fix/brief-description Branch naming: issue-number/type/brief-description .

The issue number comes from Step 2. The type is fix , feature , refactor , docs , or test . The description is a short summary of the change. For the full Git workflow (remotes, rebasing, updating PRs), see the Git Workflow Guide . Step 4: Make Your Changes ​ Find the relevant files with the search function of your editor ( Cmd+Shift+F in VS Code). Search for visible text, function names, or error messages. Frontend changes: Refresh http://localhost:8080 .

Templates reload immediately. Keep the watch process (Step 1) running for CSS/JS hot-reload. Backend changes: The web server reloads automatically when Python files change. For deeper guidance, see the Frontend Guide or Backend Guide . Step 5: Test Your Changes (~10 minutes) ​ Verify your changes manually at http://localhost:8080 Run the automated tests: sh docker compose run --rm home make test # run all tests For targeted testing, see the Testing Guide .

Step 6: Stage, Commit, and Push (~10 minutes) ​ Stage your files, run the checks, then commit and push: sh git add . pre-commit run # checks the staged files git commit -m "Brief description of the change" git push origin 123/fix/brief-description Write one short sentence that describes the change. Do not add prefixes or labels. For more guidance, see Making Changes and Creating a Pull Request . If pre-commit changes your files, stage the changed files again, and run pre-commit run again.

Then commit. WARNING Two checks can fail on your computer: mypy and generate-pot . These checks need files that exist only inside Docker. This failure is expected on your computer. The CI server runs these two checks again. All other checks must pass before you push. Step 7: Create a Pull Request (~10 minutes) ​ Go to your fork on GitHub and click "Compare & pull request" Fill out the PR template Automated checks (tests, linting) start Reviewers give feedback.

Reply to comments and push more commits as necessary For PR best practices, see Submitting Pull Requests in the upstream CONTRIBUTING guide. What Next? ​ Git Workflow — day-to-day branch, rebase, and PR update workflow Git Troubleshooting — fixes for rebase conflicts, unrelated commits, and other git problems Testing Guide — run targeted tests before you push Frontend Guide — UI templates, CSS, JS, and components Backend Guide — server-side development Local Development Architecture — which services run locally and how they connect Developers Handbook — full index of all developer guides