Skip to content

Contributing ​

IMPORTANT

Note: The content for this page is loaded at build time from the main GitHub Repo. Hence the double titles.

Contributing ​

Thanks for your interest in contributing to Open Library! We value thoughtful, collaborative contributions. Before picking up work, make sure you understand the problem, check whether someone is already working on it, and coordinate with maintainers so efforts align with project priorities. Good contributions are not just about completing an issue, but about solving the right problem clearly and respectfully.

For setup instructions, see the Quick Start guide.

How contributing works ​

  1. Find an unassigned issue
  2. Comment to describe your plan and request assignment (Good First Issues work differently)
  3. Wait for assignment
  4. Complete the work and test it
  5. Open a self-contained PR
  6. Respond to review comments clearly

Before you begin ​

We value all contributors and want to ensure a positive and collaborative environment where everyone's contributions are respected and celebrated.

Respecting Other Contributors' Work ​

Our community thrives on mutual respect. Please consider others who may already be investing their time and energy:

  • Check before starting: Look at the issue comments to see if someone has already requested assignment or is actively working on it
  • Respect current assignments: If someone is assigned to an issue, they've committed their time to it. Opening a competing PR without coordination undermines their contribution
  • Coordinate when uncertain: If you're unsure about someone's progress, ask on the issue before starting related work
  • Give space for follow-through: If an assigned issue has been inactive for 2 weeks, kindly ask whether it can be reassigned rather than assuming it's abandoned

Requesting Issue Assignments ​

Good First Issues don't need assignment; see Good First Issues below. For all other issues, please request assignment before starting work. Our maintainers triage issues weekly (or immediately for high-priority items) to ensure your contribution aligns with current priorities and prevent duplicate effort.

When requesting assignment:

  • Focus on quality over quantity: Work on one meaningful issue at a time rather than requesting many assignments
  • Show you understand the problem: Include your summary of the challenge, your proposed approach, and which files you plan to modify
  • Share your questions: If something isn't clear, ask! This helps us provide better guidance

Use AI tools responsibly. You're encouraged to use AI tools to assist with research and understanding the codebase, but please take time to truly comprehend the suggestions and present them in your own words. This demonstrates your genuine understanding and helps us have meaningful conversations about your approach.

Choosing work ​

Good First Issues ​

Browse Good First Issues — ideal for first-time contributors.

  • Only work on issues that are not assigned to anyone
  • Check the issue's comments and linked pull requests first. If there's already an open PR for the issue, please pick a different one
  • If someone else has commented that they're working on it, give them a day to work on it first. If there's still no PR after that, it's fine for you to take it on too
  • Leave a comment on the issue before you open your PR, ideally when you start, so others know it's being worked on
  • The issue is assigned automatically to the first person who opens a ready (non-draft) PR after commenting, not to whoever commented first. A draft PR doesn't claim the issue
  • Open a PR with a closing reference (for example, Closes #123); the bot assigns you automatically
  • If you skip the comment, the bot closes your PR with instructions: comment on the issue, then reopen the PR or open a new one if reopening is unavailable
  • If the issue is already assigned, coordinate with the assignee and lead before proceeding

When no Good First Issues are available ​

Opening a pull request ​

  • Test your changes before opening a PR so reviewers can focus on the code rather than basic setup issues
  • Mark the PR as draft if it's still in progress
  • Complete the pull request template fully so reviewers have the context they need
  • Make PRs self-contained so reviewers can understand them without extra context

Review comments are a normal part of the process. Most PRs need at least one round of changes before merge.

Responding to review ​

  • Reply to each review comment with the change you made or why you chose a different approach
  • Resolve all review comments before requesting another review
  • When resolving a comment, reply with "DONE" or "WON'T FIX because ..."
  • If the issue has a Lead: @username label, that person is usually the best reviewer to tag
  • Most PRs also get an automated review from @openlibrary-bot. How the code review bot works explains when it runs, what its comments and the code-review check mean, and how to respond

For issues other than Good First Issue, if you haven't heard back within one week of requesting assignment, feel free to tag the Lead: on the issue.

Community & getting help ​

Please read our Code of Conduct. We're a non-profit, open-source, inclusive project committed to creating a safe place for everyone.

Get involved:

⌂ Proxy