Docs
Search K

Appearance

Quick Start ​

  • Estimated time: 45-90 minutes
  • Difficulty: Beginner-friendly
  • Prerequisites: Docker, Git, and pre-commit installed

This guide takes you from zero to your first pull request. It's a guided walkthrough — each step links to deeper guides when you need more detail.

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.

Please review 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
git submodule init && git submodule sync && git submodule update

IMPORTANT

Use git@ (SSH), not https://. If you cloned with HTTPS, fix it here.

Build and run ​

sh
docker compose build   # 15-30 min on first run
docker compose up -d

Enable hot-reload for CSS/JS in a new terminal:

sh
docker compose run --rm home npm run watch

Open http://localhost:8080 — you should 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: Create a Branch (~5 minutes) ​

sh
git switch master
git pull upstream master
git switch -c 123/fix/brief-description

Branch naming: issue-number/type/brief-description where 123 is the GitHub issue number, type is fix, feature, refactor, docs, or test, and brief-description is a short summary of the change.

For the full Git workflow (remotes, rebasing, updating PRs), see the Git Workflow Guide.

Step 3: Find a Good First Issue (~10 minutes) ​

Browse Good First Issues

When requesting to be assigned, comment on the issue with:

  • Your understanding of the problem
  • Your proposed approach
  • Files you expect to modify
  • Any questions

See Contributor Etiquette for guidelines on respecting other contributors' work.

Step 4: Make Your Changes ​

Find relevant files using your editor's search (Cmd+Shift+F in VS Code). Search for visible text, function names, or error messages.

Frontend changes: Refresh http://localhost:8080. Templates reload immediately; start the watch process (Step 1) for CSS/JS hot-reload.

Backend changes: The web server auto-reloads when Python files change.

For deeper guidance, see the Frontend Guide or Backend Guide.

Step 5: Test Your Changes (~10 minutes) ​

  1. Manually verify your changes at http://localhost:8080
  2. Run automated tests and pre-commit checks:
sh
docker compose run --rm home make test   # run all tests
pre-commit run                           # lint and formatting

For targeted testing, see the Testing Guide.

Step 6: Commit and Push (~5 minutes) ​

sh
git add .
git commit -m "Fix: brief description of change"
git push origin 123/fix/brief-description

Step 7: Create a Pull Request (~10 minutes) ​

  1. Go to your fork on GitHub and click "Compare & pull request"
  2. Fill out the PR template
  3. Automated checks (tests, linting) will run
  4. Reviewers will provide feedback — address comments and push more commits as needed

For PR best practices, see Submitting Pull Requests in the upstream CONTRIBUTING guide.

What Next? ​