{"title":"Making Your First PR","description":null,"content":"Your first pull request is not judged only by the code. Maintainers also look at the description, the tests, the size of the change, and how you respond when they ask questions.\n\nThat may sound intimidating, but most of it comes down to making the review easy. A small, focused fix with a clear description, any expected tests, and respectful responses to feedback gives the maintainer confidence. The code matters, but the way you present and handle the pull request often determines how smoothly it moves.\n\n---\n\n# What a Good Pull Request Does\n\nA good first pull request does three things: it follows the project's rules, explains the change clearly, and handles review well.\n\n**Following the rules** starts with the contribution guide. Many active projects have a `CONTRIBUTING.md` file or a section in the `README` that explains how to set up the project, run tests, format commits, and open a pull request. Read it before you start. It saves both you and the reviewer time.\n\n**Explaining the change** means writing a description that answers the reviewer's basic questions: what changed, why it changed, and how to test it. Reviewers are busy. If they can understand the pull request quickly, it is easier for them to review.\n\n**Handling review** means treating feedback as part of the process, not as a personal judgment. A maintainer may ask for tests, a different style, a smaller change, or a different approach. That is normal. Responding clearly and making reasonable changes gives the pull request a much better chance of moving forward.\n\nRemember that the maintainer is responsible for the health of the project. Their questions and requests usually come from that responsibility. Make the review easy to follow, keep the change focused, and stay calm and respectful in the back-and-forth.\n\nThe path from idea to merge looks like this. The review step is a loop, not a single gate. A maintainer may ask for changes more than once before the pull request is ready.\n\n\n```mermaid\nflowchart LR\n A[Read contribution
guide]:::start --> B[Fork and
branch]:::step\n B --> C[Make focused
change + tests]:::step\n C --> D[Open pull request
with clear description]:::step\n D --> E{Review}:::review\n E -->|Changes requested| F[Update and
reply]:::step\n F --> E\n E -->|Approved| G[Merged]:::done\n\n classDef start fill:#00ceff,stroke:#000,color:#000\n classDef step fill:#38d9a9,stroke:#000,color:#000\n classDef review fill:#ffd43b,stroke:#000,color:#000\n classDef done fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe steps below walk through the process in order.\n\n---\n\n# From Fork to Merge, Step by Step\n\n### Read the contribution guide first\n\nFind `CONTRIBUTING.md` or the contributing section in the `README`. Look for setup steps, branch naming, commit format, test commands, linters, and any pull request checklist. Follow the project's instructions even if they differ from how you usually work.\n\n### Fork, branch, and name the branch sensibly\n\nFork the repository, create a branch from the default branch, and give it a descriptive name like `fix-quickstart-flag` instead of `patch-1`. Keep your change focused on the issue you claimed. Do not mix unrelated cleanup or formatting changes into the same pull request.\n\n### Make the change and match the existing style\n\nWrite your fix so it looks like the code around it: same patterns, naming, formatting, and level of abstraction. A pull request that matches the project style is easier to review. Run the project's formatter or linter if one exists.\n\n### Write commit messages in the project's convention\n\nSome projects use a specific commit format. Others are more casual. Check the contribution guide and recent commit history. Use a clear summary that explains the change in plain language.\n\n### Add or update tests where the project expects them\n\nFor a bug fix, the best test is one that would fail before your change and pass after it. For documentation-only changes, tests usually are not needed. If you are unsure, look at nearby code or similar pull requests to see what the project expects.\n\n### Write a pull request description that explains the change\n\nUse the template below: what changed, why it changed, how to test it, and screenshots if the change affects the UI. Link the issue it closes. Your goal is for a reviewer to understand and verify the change without having to guess.\n\n### Respond to review clearly\n\nWhen a maintainer requests changes, make them when reasonable and reply briefly when you have pushed the update. If you disagree, explain your reasoning once and stay open to their decision. If the maintainer goes quiet, one polite follow-up after a week or two is fine. Repeated reminders usually do not help.\n\n---\n\n# The Pull Request Description Template\n\nA clear description answers the questions a reviewer is likely to ask. This structure works for most first pull requests.\n\n\n```javascript\n## What\n\nOne or two sentences on what this pull request changes.\n\n## Why\n\nThe problem it fixes, linking the issue: Closes #123.\n\n## How to test\n\nSteps a reviewer can follow to verify the change:\n1. ...\n2. ...\n\n## Notes\n\nAnything the reviewer should know: trade-offs, follow-ups, screenshots\nfor visual changes. (Optional.)\n```\n\n\n**Why this works:** It explains what changed, why it matters, and how to verify it. Linking the issue with \"Closes #123\" ties the pull request to the original discussion and can close the issue automatically when the pull request is merged.\n\n---\n\n# Responding to Review Feedback\n\nHow you handle the review tells maintainers what it would be like to work with you again. Here is the difference.\n\n**Poor response:**\n\n\n```javascript\nMaintainer: Could you add a test for this and use the existing logger\ninstead of print statements?\n\nContributor: The print statements are fine for debugging and I don't\nthink a test is necessary for this small change.\n```\n\n\n**Strong response:**\n\n\n```javascript\nMaintainer: Could you add a test for this and use the existing logger\ninstead of print statements?\n\nContributor: Thanks, done. Switched to the logger and added a test\nthat fails on the old behavior. Let me know if the test placement matches\nwhere you'd want it.\n```\n\n\n**Why the strong response works:** It treats the request as part of the review process, makes the change, and confirms what was updated. The poor response may be understandable, especially when you are new, but it makes the reviewer spend more energy defending a reasonable request. When you genuinely disagree, explain once, politely, and let the maintainer make the final call.\n\n---\n\n# Mistakes That Slow Down a Pull Request\n\nEach item below costs you an extra review round-trip, turning a one-day merge into a week of back-and-forth before a maintainer even looks at the code.\n\n- **Skipping the contribution guide.** Many first pull request problems come from missing setup, test, or formatting instructions. Read the guide before coding.\n- **Opening a pull request with no useful description.** A reviewer should not have to guess what changed or how to verify it. Use the template.\n- **Bundling unrelated changes.** A pull request that fixes one bug and reformats several files is harder to review. Keep the change focused.\n- **Skipping expected tests.** If the project normally tests bug fixes, add or update a test. It gives the maintainer confidence in the change.\n- **Taking review personally.** Requested changes are normal. Treat them as part of collaboration, not as criticism of your ability.\n- **Going silent after review.** If you need time, say so. A short reply is better than disappearing.\n- **Following up too often.** One polite follow-up after a week or two is reasonable. After that, give the maintainer space.","pageType":"job-search"}

Get Premium