{"title":"Finding Your First Issue","description":null,"content":"\"Just pick an issue and fix it\" sounds simple until you open the issues tab. Some issues labeled for beginners are already claimed. Some are old. Some look small but require project knowledge you do not have yet. That is normal.\n\nYour first issue should be small, current, unclaimed, and within reach. The goal is not to prove that you can solve the hardest problem in the repository. The goal is to complete the full contribution process once: understand the issue, make a focused change, open a pull request, respond to feedback, and get the work merged.\n\n---\n\n# What a Good First Issue Looks Like\n\nA good first issue has three qualities: it looks approachable, it is genuinely small, and nobody else is actively working on it. When those are true, the contribution is manageable. When they are not, you may spend days on something too large or duplicate work someone else has already started.\n\nStart with the **labels** maintainers use to mark approachable work: \"good first issue,\" \"help wanted,\" and \"documentation.\" These labels are useful, but they are not promises. An issue can be mislabeled, outdated, or larger than it first looks.\n\nThen check the **size**. The best first issues are specific and easy to verify: a documentation correction, a broken example, a small bug with clear reproduction steps, or a minor missing option. Documentation issues are especially good first contributions because they take you through the real workflow without requiring you to understand the whole codebase.\n\nFinally, check whether the issue is **unclaimed**. Look for an assignee, a recent comment from someone saying they are working on it, or an open pull request linked to the issue. If someone is already handling it, choose another issue. Maintainers appreciate contributors who avoid duplicating other people's work.\n\nRun each candidate issue through these filters in order. If it fails one, move on.\n\n\n```mermaid\nflowchart TD\n A[Candidate issue]:::cyan --> B{Approachable label?}:::yellow\n B -->|No| X[Skip it]:::red\n B -->|Yes| C{Small and clear scope?}:::yellow\n C -->|No| X\n C -->|Yes| D{Unclaimed?}:::yellow\n D -->|No| X\n D -->|Yes| E{Within your skills?}:::yellow\n E -->|No| X\n E -->|Yes| F[Ask to work on it]:::green\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef yellow fill:#ffd43b,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nAn issue should clear all four checks before you claim it. Most issues you scan will not be the right first one, and that is fine.\n\n---\n\n# Filtering Issues Down to the Right One\n\n### Filter by the approachable labels\n\nIn the issues tab, filter for \"good first issue,\" \"help wanted,\" and \"documentation.\" Most projects let you filter by label directly in the issue search. This narrows a large issue list to work the maintainers have at least considered approachable.\n\n### Size the issue honestly\n\nRead the issue and ask what the fix actually involves. A short bug report with reproduction steps is a good size. An issue that says \"refactor the plugin system\" is not a good first issue, even if it has a beginner-friendly label. When in doubt, choose the smaller task.\n\n### Favor documentation for the very first one\n\nA documentation fix, a wrong example, an unclear setup step, or a missing parameter description can be an excellent first pull request. It is real work, it helps users, and it is usually easier to review than a code change. Do not dismiss documentation work as less valuable.\n\n### Check that it's unclaimed\n\nLook at the assignee field, the comments, and any linked pull requests. If someone is assigned or recently said they are working on it, move on. You want an issue where your effort is welcome and unlikely to duplicate someone else's work.\n\n### Check the hidden requirements\n\nAsk whether the fix depends on knowledge you do not have yet: framework internals, a domain you have never worked in, or a build system you cannot run locally. If the hidden requirement is too large, set the issue aside. The goal is a finished pull request, not an impressive abandoned branch.\n\n### Claim the issue before you start\n\nComment briefly before you start. Say you would like to work on the issue, describe your intended approach in one sentence, and ask to be assigned if that is the project's convention. This helps maintainers and other contributors know what is happening.\n\n### Consider fixing something that bugs you instead\n\nYou do not always need to start from an existing issue. If you use the tool and notice a real bug, confusing documentation, or a rough edge, you can open an issue describing it and ask whether a fix would be welcome. For a first pull request, it is usually better to confirm interest before you spend time building the change.\n\n---\n\n# Where to Look and What to Choose\n\n\n| Label / source | What it usually means | Good for a first pull request? |\n|----------------|----------------------|----------------------|\n| good first issue | Maintainers marked it as suitable for new contributors | Yes, the default starting point |\n| help wanted | Maintainers want outside help, any level | Often, check the size |\n| documentation | Documentation fixes and improvements | Yes, often a good first pull request |\n| bug, with clear steps | A defined defect you can reproduce | Yes, if small and you can reproduce it |\n| Your own discovered bug | Something you hit using the tool | Yes, genuine, but confirm it's wanted |\n| refactor / architecture | Large structural change | No, too big for a first pull request |\n\n\nThe first three rows are usually the best places to start. A small first merge gives you confidence, teaches the project workflow, and makes the second contribution easier.\n\n---\n\n# Claiming an Issue: Templates\n\nWhen you find an unclaimed issue, leave a short comment before you start. Keep it polite, specific, and easy for a maintainer to answer.\n\n**For a \"good first issue\" with no assignee:**\n\n\n```javascript\nHi, I'd like to work on this. I'll [one line on your planned approach].\nCould you assign it to me?\n```\n\n\n**When you want to confirm the approach first:**\n\n\n```javascript\nHi, I'd like to take this on. My plan is to [brief approach]. Does that\nline up with what you'd expect, or is there a direction you'd prefer?\n```\n\n\n**Why these work:** Both comments show that you read the issue and have a reasonable first plan. The second is better when there are multiple possible fixes, because it gives the maintainer a chance to steer you before you write code. Avoid commenting only \"Can I work on this?\" with no approach. It creates extra back-and-forth and does not show that you understand the task yet.\n\n---\n\n# A Vague Issue vs a Clear One\n\nThe difference between a good first issue and a frustrating one is usually scope, clarity, and whether someone else is already working on it.\n\n**Poor choice:**\n\n\n```javascript\nIssue: \"Improve performance of the rendering pipeline\"\nLabeled \"good first issue\" 10 months ago. No steps to reproduce the\nproblem, no scope, and no recent maintainer guidance. Two older comments\nsay \"I'll look into this,\" but there is no current direction.\n```\n\n\n**Good choice:**\n\n\n```javascript\nIssue: \"Docs: the quickstart example uses a removed flag --legacy\"\nLabeled \"documentation,\" opened 3 days ago, no assignee. The fix is\nupdating one command in the README to the current flag.\n```\n\n\n**Why the good choice works:** The performance issue is vague and likely larger than the label suggests. The documentation issue is recent, specific, unclaimed, and easy to verify. It still takes you through the full contribution workflow, which is exactly what you need from a first pull request.\n\n---\n\n# Mistakes When Choosing an Issue\n\nPick the wrong issue here and you can spend a weekend on a fix that was never yours to make or was never as small as the label promised.\n\n- **Picking an issue that is already claimed.** An assignee, a recent \"I'll take this,\" or an open linked pull request usually means someone is already working on it.\n- **Trusting the label more than the scope.** \"Good first issue\" on a vague task is still a vague task. Read the issue and decide whether you can finish it.\n- **Skipping documentation issues.** A documentation fix is a real merged pull request and a good way to learn the workflow. It is a practical first contribution, not a lesser one.\n- **Claiming with no plan.** \"Can I work on this?\" is less helpful than a short note explaining what you plan to change.\n- **Ignoring hidden dependencies.** If the issue requires knowledge or setup you do not have yet, it may stall. Pick something you can complete.\n- **Claiming too many issues at once.** Claim one issue, finish it, then take another. This builds trust with maintainers.","pageType":"job-search"}

Get Premium