Making your first contribution to open source projects feels like standing at the edge of a diving board. You know you want to jump in, but the workflow seems intimidating, and the fear of making a mistake holds you back. Pull requests are the gateway to open source contribution, yet the process of creating one can feel overwhelming when you are just getting started.
Here is the good news: creating pull requests follows a predictable pattern. Once you understand the workflow, you will find yourself submitting contributions with confidence. This guide walks you through every step of creating your first pull request, from forking a repository to celebrating when your code gets merged. If you have already found a good first issue to work on through sites like helpwanted.dev or GitHub’s issue search, you are ready to begin.
Prerequisites: What You Need Before Starting
Before diving into the pull request workflow, make sure you have these essentials in place.
GitHub Account
You need a GitHub account to contribute to most open source projects. If you do not have one yet, head to github.com and sign up. Your GitHub account will be your identity in the open source community, so choose a username you are comfortable using professionally.
Git Installed Locally
Git must be installed on your computer. Check if you have it by running:
git --version
If Git is not installed, download it from git-scm.com and follow the installation instructions for your operating system.
Basic Command Line Familiarity
You should be comfortable opening a terminal or command prompt and navigating directories. Knowing commands like cd, ls (or dir on Windows), and basic file operations will help you follow along.
A Good First Issue to Work On
The best way to start is with issues specifically labeled for new contributors. Look for labels like “good first issue” or “help wanted” on repositories you want to contribute to. Tools like helpwanted.dev aggregate thousands of these beginner-friendly issues across popular projects, making it easy to find your first contribution opportunity.
Your Favorite Code Editor
Have a code editor ready. Visual Studio Code, Sublime Text, or any editor you are comfortable with will work perfectly.
Understanding the Pull Request Workflow
A pull request is your way of saying, “Hey maintainers, I made some changes that I think would improve this project. Would you review them and consider adding them to the codebase?”
The complete workflow looks like this:
- Fork the repository (create your own copy)
- Clone it to your computer
- Create a new branch for your changes
- Make your code changes
- Commit your changes with a descriptive message
- Push to your forked repository
- Open a pull request to the original project
This workflow exists for good reasons. It protects the main codebase from untested changes while enabling maintainers to review contributions carefully. The review process ensures code quality and helps new contributors learn best practices.
Understanding the difference between a fork and a clone is essential. A fork is a copy of the repository that lives on your GitHub account. A clone is a copy of that fork that lives on your local computer. You make changes locally, push them to your fork, and then request that those changes be “pulled” into the original repository, hence the name “pull request.”
Step 1: Fork the Repository
Forking creates your personal copy of the project on GitHub. This forked repository belongs to you, so you have full permission to make changes without affecting the original project.
To fork a repository:
- Navigate to the repository you want to contribute to on GitHub
- Look for the “Fork” button in the upper right corner of the page
- Click it and wait a few seconds while GitHub creates your copy
After forking, you will have a repository at github.com/YOUR-USERNAME/repository-name. This is your forked repository where you will push your changes.
The fork maintains a connection to the original repository (called the “upstream”), which allows you to sync changes later. You can fork any public repository on GitHub to start contributing.
Step 2: Clone Your Fork Locally
Now you need to get the code onto your computer so you can work on it. Open your terminal and run:
git clone https://github.com/YOUR-USERNAME/repository-name.git
Replace YOUR-USERNAME with your actual GitHub username and repository-name with the project name.
Navigate into the project directory:
cd repository-name
Verify your remotes are set up correctly:
git remote -v
You should see output showing origin pointing to your forked repository. Next, add the original repository as an upstream remote. This allows you to sync your fork with the latest changes from the main project:
git remote add upstream https://github.com/ORIGINAL-OWNER/repository-name.git
Verify both remotes are configured:
git remote -v
You should now see both origin (your fork) and upstream (the original repository) listed.
Step 3: Create a New Branch
Never make changes directly on the main branch. Creating a new branch isolates your work and makes it easy to manage multiple contributions simultaneously.
Branch naming conventions help maintainers understand what your changes do at a glance. Common patterns include:
fix/issue-123-typo-in-readmefor bug fixesfeature/add-dark-modefor new featuresdocs/update-installation-guidefor documentation updates
Create and switch to your new branch with a single command:
git checkout -b fix/issue-123-description
Or if you prefer the newer Git syntax:
git switch -c fix/issue-123-description
Keep each branch focused on a single issue or feature. If you want to work on multiple issues, create separate branches for each. This makes pull requests easier to review and increases the chance they get merged quickly.
You can verify you are on the correct branch by running:
git branch
The asterisk indicates your current branch.
Step 4: Make Your Changes
Now comes the fun part: actually writing code! Before you start typing, take time to understand what needs to be done.
Read the Issue Carefully
Go back to the good first issue you chose and read it thoroughly. Look for:
- A clear description of the problem or feature
- Any specific requirements or constraints
- Comments from maintainers with additional context
- Links to relevant files or documentation
Understand the Existing Code
Before modifying code, explore how the project is structured. Look at similar code in the codebase to understand the patterns and conventions used. Check the contribution guidelines if the project has them, as many projects document their expectations for new contributors.
Follow the Project’s Coding Style
Match the existing code style. If the project uses tabs, use tabs. If they use single quotes, use single quotes. Consistency matters more than personal preference when contributing to others’ projects.
Tips for Making Changes
- Make small, focused changes that address only the issue at hand
- Test your changes locally before committing
- Run existing tests if the project has them:
npm test,pytest, or whatever the project uses - Check linting and formatting requirements: many projects use tools like ESLint, Prettier, or Black
Step 5: Commit Your Changes
After making your changes, you need to save them with a commit. A commit is a snapshot of your changes with a message explaining what you did.
First, stage the files you want to include:
git add .
Or add specific files:
git add src/specific-file.js
Check what is staged:
git status
Now commit with a meaningful message:
git commit -m "Fix typo in README installation section
Closes #123"
Writing Good Commit Messages
Your commit message helps maintainers understand your changes during the review process. Follow these best practices:
- Start with a verb: Fix, Add, Update, Remove, Refactor
- Keep the first line under 50 characters: This shows properly in Git logs
- Reference the issue number: Use “Closes #123” or “Fixes #123” to automatically link and close the issue when merged
- Add details in the body if needed: Separate from the subject with a blank line
Example of a detailed commit message:
git commit -m "Add dark mode toggle to settings page
- Add toggle switch component
- Store preference in localStorage
- Apply theme on page load
Fixes #456"
Step 6: Push to Your Fork
Your commits exist only on your local machine. Push them to your forked repository on GitHub:
git push origin fix/issue-123-description
If this is your first push to this branch, you might need to set the upstream:
git push -u origin fix/issue-123-description
After pushing, visit your forked repository on GitHub. You should see your new branch listed, often with a prompt to create a pull request.
Step 7: Create the Pull Request
This is the moment your first contribution becomes real. You are about to submit your work for review.
Navigate to the original repository on GitHub (not your fork). You will likely see a yellow banner suggesting you “Compare & pull request” for your recently pushed branch. Click it.
If you do not see the banner, click “Pull requests” in the repository navigation, then “New pull request.” Select “compare across forks” and choose your fork and branch.
Filling Out the Pull Request Template
Many open source projects have pull request templates. Fill them out completely. If there is no template, include:
Title: Make it clear and descriptive. Often it mirrors your commit message.
Description: Explain your changes thoroughly:
## What does this PR do?
Fixes the typo in the installation section of the README where "dependancies" was spelled incorrectly.
## Related Issue
Closes #123
## How to Test
1. Open the README.md file
2. Navigate to the Installation section
3. Verify "dependencies" is spelled correctly
## Screenshots (if applicable)
N/A - text change only
Before Submitting
- Review the “Files changed” tab to see exactly what you are submitting
- Make sure you have not included any unintended changes
- Verify the base branch is correct (usually
main)
Click “Create pull request” and celebrate! You have just submitted your first pull request to an open source project.
Step 8: Respond to Code Review
After submitting your pull request, maintainers will review your changes. This review process is normal and valuable. Even experienced contributors receive feedback on their pull requests.
Common Review Requests
- Code style changes: Formatting, naming conventions, or structural improvements
- Additional tests needed: Maintainers may ask you to add tests for your changes
- Logic improvements: Suggestions for more efficient or cleaner approaches
- Documentation updates: Adding comments or updating docs to reflect your changes
Responding to Feedback
When you receive feedback, make the requested changes locally:
git add .
git commit -m "Address review feedback: improve variable naming"
git push origin fix/issue-123-description
The new commits automatically appear in your pull request. No need to create a new one.
Best Practices for Code Review
- Be patient: Maintainers are often volunteers with limited time
- Be professional: Thank reviewers for their feedback
- Ask questions: If feedback is unclear, politely ask for clarification
- Learn from it: Code review is one of the best ways to improve as a developer
Keeping Your Fork Updated
Over time, the original repository receives new commits from other contributors. Keep your fork synchronized to avoid conflicts.
Fetch the latest changes from upstream:
git fetch upstream
Switch to your main branch:
git checkout main
Merge the upstream changes:
git merge upstream/main
Push the updates to your forked repository:
git push origin main
If your pull request is still open and the main branch has changed significantly, you might need to rebase your branch:
git checkout fix/issue-123-description
git rebase main
If there are conflicts, Git will guide you through resolving them.
Common Issues and Solutions
Even experienced contributors run into problems. Here are solutions to common issues:
| Problem | Solution |
|---|---|
| Merge conflicts | Pull latest main, resolve conflicts manually, then push again |
| CI checks failing | Read the error logs carefully, fix the issues, and push a new commit |
| ”Stale” PR warning | Rebase your branch on the latest main branch |
| Accidentally committed to main | Create a new branch from your commits, then reset main |
| Push rejected | Pull the latest changes first: git pull origin branch-name |
If you get stuck, do not hesitate to ask for help in the pull request comments. The open source community is generally welcoming to new contributors who make genuine efforts.
What Happens After Your PR is Merged?
When a maintainer merges your pull request, you officially become an open source contributor! Take a moment to celebrate this accomplishment.
Clean up your local environment by deleting the merged branch:
git branch -d fix/issue-123-description
GitHub offers a button to delete the remote branch after merging. Click it to keep your forked repository tidy.
Now that you have completed your first contribution, look for your next issue. Visit helpwanted.dev to discover more good first issue opportunities across thousands of projects. Consider returning to the same project where you just contributed. Maintainers appreciate regular contributors, and your familiarity with the codebase makes future contributions easier.
Conclusion
You now know the complete workflow for creating pull requests: fork the repository, clone it locally, create a new branch, make your changes, commit with a meaningful message, push to your forked repository, and open the pull request. The review process might add a few iterations, but that is part of learning and growing as a developer.
Your first pull request is always the hardest. The workflow feels unfamiliar, and you worry about making mistakes. But every experienced open source contributor started exactly where you are now. With each contribution, the process becomes more natural.
Ready to put this knowledge into practice? Head to helpwanted.dev to find your first issue. Filter by language, difficulty, or project type to find something that matches your skills and interests. Your first contribution is just a few Git commands away.