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 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

Comment on the issue to request assignment. Write:

  • Your understanding of the problem
  • Your proposed solution
  • The files you plan to change
  • Your questions, if any

Wait for assignment before you start. Assignment prevents two people from doing the same work.

See Contributor Etiquette for more guidelines.

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) ​

  1. Verify your changes manually at http://localhost:8080
  2. 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) ​

  1. Go to your fork on GitHub and click "Compare & pull request"
  2. Fill out the PR template
  3. Automated checks (tests, linting) start
  4. 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? ​