5. Pick a repository and an issue

A GitHub repository, often shortened to repo, holds a project's files and history. An issue is a discussion about a bug, question, or requested change. A pull request (PR) proposes changes for maintainers to review. When maintainers accept a pull request they merge it (people also say it lands). A commit is one saved change in the project's history, and continuous integration (CI) is the set of automated tests that runs on each pull request.

Which of the organization's repositories?

Many organizations own dozens of repositories, and only a few are where mentors spend their time.

git-into-gsoc repos "SymPy" --language python

The examples on this page use SymPy only to show what the commands print. Run them on your own shortlist, and see the note on SymPy in step 4. Issue references such as OWNER/REPO#NUMBER are placeholders. OWNER is for organization, REPO is for repository and NUMBER is for the issue number. Please replace them with an exact issue you choose.

The table ranks the organization's active repositories. The strongest signal is whether the organization's GSoC ideas page names the repository. After that come open, unassigned beginner issues, recent pushes, stars, and whether the repository is written in your language. The caption tells you whether the ideas page could be read; some wikis block automated readers, in which case the ranking uses activity and beginner issues only. You can also pass a GitHub organization login directly, such as repos sympy.

Will a newcomer's PR land here?

git-into-gsoc repo sympy/sympy

Expect a grade from A to F, the evidence behind it, and setup hints. The signals that matter most for you:

What the grade means

Each signal adds points, and the points add up to 100; the grade, the advice under it, and the command to run next all follow the score. Under the checks, "Where it lost points" names each signal that earned less than its most, and why. Sources and limitations has the point table, the grade boundaries, and the two rules that can hold a grade down.

"Getting set up" lists the toolchain files found in the repository root, whether a dev container exists (one click in Codespaces or VS Code gets you a working environment), the CONTRIBUTING link, and the chat channels it mentions. Read the README and CONTRIBUTING on GitHub before writing code. A high grade does not guarantee mentoring, and a missing file can mean the guide lives elsewhere. If the repository is archived, look for the project's current repository before continuing.

git-into-gsoc repo sympy/sympy --track          # same check, and saves the repo to your progress

When you have one or two repositories you want to work in, mark the step done:

git-into-gsoc progress complete_phase --phase evaluate

Get your bearings in the repository

git-into-gsoc orient sympy/sympy

Before you look for an issue, spend one session learning how the project is put together. orient prints a code map with entry points, the command CI really runs for tests, who writes most of the code (commit authors and CODEOWNERS), and the rules you must follow before opening one (sign-offs, commit style, templates, AI disclosure), each with the file it came from. CODEOWNERS is a GitHub file, in .github/, the repository root, or docs/, that names the people or teams asked to review changes to each path. A sign-off is a line in a commit message, usually Signed-off-by: Your Name <you@example.com>, that says you wrote the change or have the right to submit it. Then clone the repository, build it, run its test suite once, and read the files behind the feature you care about. When you can say where a change would go and how you would test it, mark the phase done:

git-into-gsoc progress complete_phase --phase orient

Introduce yourself to the community

Before you claim an issue, say hello in the organization's public channel: the chat or mailing list that org lists. A short introduction that mentions something concrete you read or ran with orient makes your later comment on an issue land better, and the official contributor guide asks for public contact first.

git-into-gsoc draft intro --org "SymPy"

draft intro and draft question give you a short, specific structure for a first message; fill it in with your own words. When you have written your message, git-into-gsoc draft intro --check my-message.md checks it before you post: placeholders you forgot to replace, phrases that read as machine-written, or a first message that is only a greeting. Read recent conversations to learn how the project talks and decides. When you ask for help, say what you tried, the exact error without private data, and the relevant versions. Ask in public rather than messaging maintainers privately, do not send the same request to several people, and give volunteers time to reply.

git-into-gsoc progress complete_phase --phase community

Find an issue that is actually free

git-into-gsoc issues --repo sympy/sympy -n 5
git-into-gsoc issues --language python -n 10

Without --repo or --org, the search covers only repositories owned by GSoC organizations that use your language, and each result shows the organization it belongs to. Add --scope all to search every repository on GitHub. The search asks GitHub for open issues labelled "good first issue" or "help wanted" (with "good first issue" ranked first) that have no assignee, no linked PR, are not in archived repositories, and were updated in the last year. The top candidates are then verified against their timelines.

Each result has a status:

Status Meaning What to do
available Open, unassigned, no open PR, no recent claim Read the thread, reproduce the problem, then comment with a plan
claimed Someone asked to work on it and the claim was active in the last 30 days, a maintainer approved a claim that was active in the last 60 days, or a label marks it as taken. A claim stays active while its author keeps commenting or a maintainer checks in with them, so an approval from long ago no longer counts Pick another issue; do not compete
contested Three or more people asked in the last 60 days Avoid; this is the GSoC-season trap
likely_taken An open PR references the issue, or a comment points at an open PR that covers it Choose another unless the PR is abandoned
not_open A label such as "Idea for Discussion" or "on hold", or the project itself, says it is not taking claims yet, or the repository is archived (read-only) Choose another; do not comment asking for it
assigned GitHub shows an assignee Choose another unless maintainers invite collaboration
stale No activity for a year and no maintainer engagement Ask whether it is still relevant before investing time
closed Issue is closed Look for another
unknown The tool could not fetch the timeline Open GitHub and check manually

To see where to start reading for an issue, ask for pointers:

git-into-gsoc pointers OWNER/REPO#NUMBER

It lists the files the issue names, past fixes of similar issues and the files they touched, and how big a typical fix is. It never proposes a fix; it tells you where to look.

Before you comment, check one issue in depth:

git-into-gsoc issue OWNER/REPO#NUMBER
git-into-gsoc issue https://github.com/OWNER/REPO/issues/NUMBER

It lists linked PRs with their state and author, every claim with its age and whether a maintainer approved it, whether maintainers have engaged at all, and caveats such as "Merged PR #12 mentions this issue; read it to see whether it already fixes part of it". A closed or merged pull request that only mentions the issue is marked "mentions this issue", so you can tell it from work on it. Below that is a short checklist to complete before you write anything in the thread. If an open pull request already references the issue but has been quiet for ninety days or more, it says so and suggests asking its author in the thread before you start. If an earlier pull request that said it fixes the issue was closed without merging, it says so: read that pull request's review comments before you start, because they show what the maintainers expect. A closed one that only mentions the issue is marked as a mention instead; if it did try, its review comments are still worth reading.

Availability is an estimate from public data. The tool reads up to 500 timeline events, so very long threads may hide a claim. Read the discussion yourself before starting. Results are cached briefly; add --output json to see the full assessment.

Choose one understandable task

Look for a clear problem, steps to reproduce it, and an explanation of the expected outcome. Documentation and tests are useful contributions too. Choose something small enough that you can explain the planned change.

Before commenting, read the project's assignment policy. If confirmation is needed, say what you tried and what you plan to do, in your own words:

I reproduced this using [version and steps]. I think the relevant code is
[file or function], and I would like to [specific change]. Does that
approach fit, or is there a direction you would prefer?

Replace the brackets with real observations. Do not post the template unchanged, and never post a bare "can I work on this?". git-into-gsoc draft claim --issue OWNER/REPO#NUMBER prints a skeleton that already respects the repository's claim rules; fill it with what you found. If someone is already working on it, find another issue or ask whether they welcome help.

git-into-gsoc issue OWNER/REPO#NUMBER --track   # same check, and saves the issue to your progress

When you have one issue you can reproduce and explain, mark the step done:

git-into-gsoc progress complete_phase --phase find_issues

Ready to move on: you can explain the problem, have introduced yourself in the project's channel, have checked the discussion, and know the project's contribution process.

Next: make your first contribution ยท Guide contents

Source: docs/guide/05-choose-an-issue.md on GitHub. Corrections are welcome.