Using Fork and Upstream Strategy for Open Source

Work with upstream repositories and contribute to open source.

Open source software thrives on collaboration. Whether you’re fixing a typo or adding a major feature, contributing to public repositories can be rewarding—and, at times, a bit daunting. Among the many workflows you'll encounter in open source, "fork and upstream" is one of the most essential, especially when you don’t have direct write access to a repository.

This blog post will guide you through the fork and upstream workflow, explaining what it is, why it matters, and how you can use it to contribute seamlessly to open source projects.

What is the Fork and Upstream Workflow?

When working with open source projects on platforms like GitHub or GitLab, you typically don’t have permission to push changes directly to the main repository (often called the "upstream" repository). The fork and upstream workflow lets you make changes safely and propose them for inclusion in the original repo.

Key Terminology

  • Origin: Your copy (fork) of the original repo, where you'll commit and push your changes.
  • Upstream: The original repository you want to contribute to.

The typical flow:

  1. Fork the upstream repository (creating a copy under your account).
  2. Clone your fork to your local machine.
  3. Set upstream remote to point to the original repository.
  4. Work on your changes in your local clone.
  5. Push changes to your fork (origin).
  6. Open a pull request from your fork to the upstream repository.

Why Use Fork and Upstream?

  • Safe Collaboration: You don’t need write access to the main repo.
  • Isolation: Your changes remain separate until you want to propose them.
  • Staying Up-to-date: You can easily sync your fork with new updates from the upstream repository.
  • Traceability: Maintainers can easily review, merge, or provide feedback on your changes via pull requests.

Step-by-Step Guide to Fork and Upstream Workflow

Let’s walk through the process using Git and GitHub as examples.

1. Fork the Repository

Go to the GitHub page of the project you want to contribute to and click the Fork button. This creates a copy under your GitHub account.

2. Clone Your Fork

Clone your fork to your local machine:

git clone https://github.com/<your-username>/<project>.git
cd <project>

3. Add the Upstream Remote

Link the original repository as upstream so you can fetch any new updates:

git remote add upstream https://github.com/<original-author>/<project>.git

Verify your remotes:

git remote -v

You should see origin (your fork) and upstream (the main repo).

4. Sync Your Fork Regularly

Before making changes, always ensure your local repository is up to date with upstream:

git fetch upstream
git checkout main
git merge upstream/main

Or, to simply rebase:

git fetch upstream
git checkout main
git rebase upstream/main

5. Create a Branch for Your Work

Never work directly on main. Create a feature branch:

git checkout -b add-my-feature

Make your changes, add, and commit:

git add .
git commit -m "Describe your changes"

6. Push Changes to Your Fork

Push your branch to your fork:

git push origin add-my-feature

7. Create a Pull Request

Go to your fork on GitHub. You’ll see an option to create a pull request to the upstream repository. Fill out the details and submit.

8. Respond to Review

Address any feedback, pushing new changes to your branch as needed. Your pull request will automatically update.

Best Practices

  • Sync upstream regularly: Avoid merge conflicts by keeping your fork up to date.
  • Use descriptive branch names and commit messages: Make your work easy to review and track.
  • Participate in discussions: Be responsive to maintainer feedback.
  • Follow project guidelines: Often documented in CONTRIBUTING.md.

Conclusion

The fork and upstream workflow empowers anyone—regardless of permission level—to take part in open source software development. By forking, syncing, and contributing via pull requests, you can collaborate efficiently, help improve projects you love, and grow as a developer. Happy contributing!

Back to All Articles