# Your First Open-Source Pull Request: From Issue to Merge

Contributing to open source sounds intimidating the first time. Big codebases, strangers reviewing your code, Git commands you only half remember. The good news: the process is the same almost everywhere, and once you have done it once, it stops being scary.

This guide walks through the full flow, step by step:

**Issue → Fork → Clone → Branch → Work → Pull Request → Review → Merge**

## 1. Find a project and an issue

Start with a project you actually use or care about. You will understand the context faster and stay motivated.

Then look for an issue that fits a first contribution:

- Filter issues by labels like `good first issue`, `help wanted`, or `documentation`
- Read the project's `README.md` and `CONTRIBUTING.md` before anything else
- Check that the issue is still open and nobody else is already working on it
- Leave a short comment such as "I'd like to work on this, can I take it?" and wait for a maintainer to confirm

Small is good. A typo fix, a missing test, or a docs improvement is a perfectly valid first PR.

## 2. Fork the repository

You cannot push directly to someone else's repository, so you make your own copy. On GitHub, click **Fork** at the top right of the repository page. You now have `github.com/<your-username>/<project>`.

## 3. Clone your fork

```bash
git clone https://github.com/<your-username>/<project>.git
cd <project>
git remote add upstream https://github.com/<original-owner>/<project>.git
```

The `upstream` remote lets you pull in the latest changes from the original project later.

## 4. Create a branch

Never work directly on `main`. Create a branch named after the change:

```bash
git checkout -b fix/typo-in-install-docs
```

One branch per issue keeps your pull requests clean and easy to review.

## 5. Do the work

- Follow the setup steps in the project docs and make sure the project runs locally
- Keep the change focused on the issue, nothing extra
- Match the existing code style and naming
- Run the tests and linters the project uses before committing

Then commit with a clear message:

```bash
git add .
git commit -m "docs: fix typo in installation guide"
```

Tip: check whether the project uses a commit convention (like Conventional Commits) and follow it.

## 6. Sync and push

Before opening the PR, make sure your branch is up to date with the original project:

```bash
git fetch upstream
git rebase upstream/main
git push origin fix/typo-in-install-docs
```

## 7. Open the pull request

GitHub will show a **Compare & pull request** button on your fork. A good PR description has:

- **What** changed, in one or two lines
- **Why**, with a link to the issue (`Fixes #123` closes it automatically on merge)
- **How you tested it**
- Screenshots if the change is visual

Fill in the PR template if the project has one.

## 8. Handle maintainer feedback

This is the part that matters most. Maintainers may ask for changes, and that is normal, not a rejection.

- Reply politely and ask questions if something is unclear
- Push fixes to the same branch, and the PR updates automatically
- Be patient: maintainers are often volunteers, so a review can take days or weeks
- If there is no response after a week or two, a friendly follow-up comment is fine

## 9. Merge and celebrate

Once approved, a maintainer merges your PR and your name shows up in the project's history. Clean up afterwards:

```bash
git checkout main
git pull upstream main
git branch -d fix/typo-in-install-docs
```

## Common mistakes to avoid

- Starting work without commenting on the issue first
- Opening one giant PR that changes many unrelated things
- Ignoring the contributing guidelines or failing tests
- Taking review comments personally
- Using a work email for commits when the contribution is personal (set `git config user.email` per repository)

## Final thoughts

Your first pull request does not need to be impressive. It needs to be correct, focused, and respectful of the maintainers' time. Do that once, and the second one gets much easier.

If you are planning your first contribution and get stuck, drop a comment below. Happy contributing!