GitHub Collaboration – Fork, Upstream and Open Source Workflow
Imagine finding a useful open-source project on GitHub. You notice a bug and know how to fix it. However, you do not have permission to change the original repository. How can you contribute your solution?
This is where GitHub collaboration becomes important. Developers use forks, branches, remote repositories, and pull requests to work together without directly changing another developer's code.
- What a fork is and how it differs from a clone.
- What
originandupstreammean. - How to contribute to an open-source project.
- How to keep your fork synchronised with the original repository.
- How to create a branch, push changes, and open a pull request.
- How to handle reviews, conflicts, and contribution best practices.
1. Why Do Developers Need GitHub Collaboration?
Modern software projects are rarely developed by one person. Multiple developers work on different features, fixes, and improvements.
Consider an open-source payment validation library. A developer discovers that a validation rule does not handle a particular input correctly. The developer wants to fix the issue and share the improvement with the project maintainers.
Directly changing the original repository may not be possible. The repository owner controls who can push changes to it.
GitHub provides a collaboration workflow that solves this problem. A contributor creates a separate copy, makes changes, and proposes those changes to the original project.
Common collaboration scenarios
- Contributing bug fixes to open-source projects.
- Adding features to an existing application.
- Improving documentation and examples.
- Reviewing code written by other developers.
- Maintaining a personal fork of an external project.
- Working with distributed development teams.
2. What Is a Fork in GitHub?
A fork is a GitHub-hosted copy of another repository under your own GitHub account or organisation.
It gives you a separate repository where you can experiment, create branches, commit changes, and push your work.
A fork does not automatically give you permission to modify the original repository. Your changes remain in your fork until you propose them through a pull request.
Example
Assume the original project belongs to an organisation:
https://github.com/open-source-team/payment-validator
You fork it into your account:
https://github.com/your-username/payment-validator
Both repositories contain their own repository history and branches. You can now make changes in your copy without directly modifying the original project.
git clone.3. Fork vs Clone: What Is the Difference?
These two operations are related, but they solve different problems.
| Fork | Clone |
|---|---|
| Creates a GitHub-hosted copy of a repository. | Creates a local copy on your computer. |
| Performed through GitHub. | Usually performed using the Git command line or a Git client. |
| Creates a repository under your account or organisation. | Creates a working directory on your machine. |
| Useful when you cannot directly push to the original repository. | Useful when you need to work with repository files locally. |
| Can be used as the source of a pull request. | Does not create a GitHub repository by itself. |
In a typical open-source contribution, we use both operations:
- Fork the original repository on GitHub.
- Clone our fork to the local machine.
- Make changes locally.
- Push changes to our fork.
- Open a pull request against the original repository.
4. What Are Origin and Upstream?
This is one of the most important concepts in fork-based collaboration.
A remote is a named reference to another Git repository. It allows Git to communicate with repositories hosted elsewhere.
When you clone your fork, Git normally creates a remote named origin.
In a fork-based workflow, developers commonly use two remotes:
- origin: Your fork on GitHub. You usually push your changes here.
- upstream: The original repository. You usually fetch its latest changes from here.
Example repository arrangement
Your fork is the destination for your changes. The upstream repository is the source of the original project's updates.
Why do we need two remotes?
Your fork is where you have permission to push changes. The original repository may not allow direct pushes from contributors.
You still need the original project's latest changes. The upstream remote provides access to those updates.
| Remote | Points to | Common operation |
|---|---|---|
origin |
Your fork | git push origin |
upstream |
Original repository | git fetch upstream |
5. Complete Open-Source Contribution Workflow
Now let's follow a realistic example. We will contribute a validation improvement to an open-source payment library.
Assume the original repository is:
https://github.com/open-source-team/payment-validator.git
Replace the example repository and username with the actual project details when practising.
Step 1: Fork the original repository
Open the original repository on GitHub. Select the Fork option and create a copy under your account.
After the fork is created, your repository URL will look similar to this:
https://github.com/your-username/payment-validator
You now have your own GitHub repository based on the original project.
Step 2: Clone your fork
Open a terminal and clone the repository that belongs to your account.
Clone your fork
git clone https://github.com/your-username/payment-validator.git
cd payment-validator
This creates a local working directory. Git also configures the cloned repository as the origin remote.
Check the configured remote
git remote -v
Example output
origin https://github.com/your-username/payment-validator.git (fetch)
origin https://github.com/your-username/payment-validator.git (push)
Step 3: Add the upstream remote
Next, connect your local repository to the original project.
Add the original repository
git remote add upstream https://github.com/open-source-team/payment-validator.git
Check both remotes again:
git remote -v
Example output
origin https://github.com/your-username/payment-validator.git (fetch)
origin https://github.com/your-username/payment-validator.git (push)
upstream https://github.com/open-source-team/payment-validator.git (fetch)
upstream https://github.com/open-source-team/payment-validator.git (push)
Step 4: Fetch the latest upstream changes
The original project may receive updates while you are working. Fetch those changes before creating your contribution branch.
git fetch upstream
This downloads updated objects and remote-tracking references. It does not automatically merge them into your current branch.
You can inspect the available remote branches using:
git branch -r
For a repository whose default branch is main, you may see:
origin/HEAD -> origin/main
origin/main
upstream/main
Step 5: Synchronise your local main branch
Before starting new work, update your local main branch with the original repository's latest changes.
git switch main
git merge upstream/main
This merges the fetched upstream main branch into your local main branch.
If you prefer a linear history, you can use the following alternative:
git switch main
git rebase upstream/main
After updating local main, push it to your fork if required:
git push origin main
Step 6: Create a feature branch
Do not make your contribution directly on the main branch. Create a separate branch for the issue or feature.
git switch -c fix/payment-validation-rule
A branch is an independent line of development. It helps keep your contribution separate from other work.
Check your current branch:
git branch --show-current
fix/payment-validation-rule
Step 7: Make and test your changes
Update the relevant source files. For example, you may correct a validation rule in the payment library.
Review the changed files:
git status
git diff
Run the project's tests and follow its contribution guidelines. Do not assume that a successful commit means the code is correct.
Step 8: Commit your changes
Stage only the files related to your contribution.
git add src/PaymentValidator.cs
git commit -m "Fix payment input validation"
A commit records a snapshot of your staged changes in Git history.
Step 9: Push your feature branch to origin
Push the branch to your own fork. The -u option sets the upstream tracking branch for future pushes and pulls.
git push -u origin fix/payment-validation-rule
Your branch is now available on your GitHub fork.
Step 10: Open a pull request
Open your fork on GitHub. GitHub may display a prompt to create a pull request for your recently pushed branch.
When creating the pull request, verify the base and compare repositories carefully.
| Pull request field | Repository and branch |
|---|---|
| Base repository | open-source-team/payment-validator |
| Base branch | main |
| Head repository | your-username/payment-validator |
| Compare branch | fix/payment-validation-rule |
Write a clear title and description. Explain the problem, the solution, and the tests you performed.
Submit the pull request. The original project's maintainers can now review your contribution.
6. Understanding the Complete Collaboration Flow
The following diagram shows how a contribution moves from your local machine to the original project.
A contributor works in their fork. The original maintainers review and decide whether to merge the proposed changes.
7. What Happens After You Open a Pull Request?
Opening a pull request does not automatically add your changes to the original project.
The project maintainers review your proposed changes. They may ask questions, suggest improvements, or request additional tests.
Common pull request review stages
1. Automated checks
GitHub Actions or another CI system may run tests, builds, formatting checks, and security checks.
2. Code review
Maintainers inspect the changes for correctness, readability, maintainability, and compatibility.
3. Review comments
Reviewers may leave comments on specific lines. They may request changes before approval.
4. Update your branch
Make the requested changes locally. Commit and push them to the same feature branch.
The pull request will reflect the new commits automatically.
5. Approval and merge
When the required checks and reviews are complete, an authorised maintainer can merge the pull request.
8. How to Keep Your Fork Updated
Open-source repositories continue to change. Other contributors may merge new features and bug fixes while you work.
Your fork can become outdated. You should periodically synchronise it with the original repository.
Option 1: Update using merge
Fetch the latest changes from upstream and merge them into your local main branch.
git fetch upstream
git switch main
git merge upstream/main
git push origin main
This approach preserves the existing commit history and creates a merge commit when necessary.
Option 2: Update using rebase
You can also replay your local commits on top of the latest upstream main branch.
git fetch upstream
git switch main
git rebase upstream/main
git push origin main
Rebase creates a linear history by replaying commits. It rewrites commit identities for the commits being replayed.
git push --force-with-lease. Never use force push casually on shared branches.9. How to Resolve Merge Conflicts in a Contribution
A merge conflict happens when Git cannot automatically combine changes. This often occurs when two branches modify the same part of a file.
For example, your feature branch changes a validation method. The upstream main branch changes that same method before your contribution is merged.
Git needs you to decide how the final code should look.
Example conflict markers
<<<<<<< HEAD
public bool IsValid(string value)
{
return !string.IsNullOrWhiteSpace(value);
}
=======
public bool IsValid(string value)
{
return value != null && value.Length > 0;
}
>>>>>>> upstream/main
The markers identify the conflicting sections. They are not valid C# code and must be removed after resolving the conflict.
Typical conflict resolution steps
- Open the files reported by Git.
- Understand both sets of changes.
- Choose or combine the correct implementation.
- Remove the conflict markers.
- Run relevant tests.
- Stage the resolved files.
- Complete the merge or rebase operation.
For a merge conflict, the commands commonly look like this:
git status
# Edit the conflicted files and resolve the markers.
git add src/PaymentValidator.cs
git commit
When resolving a rebase conflict, use the following command after staging the resolved files:
git add src/PaymentValidator.cs
git rebase --continue
If you need to cancel an in-progress merge or rebase, use the corresponding abort command:
git merge --abort
git rebase --abort
10. Fork-Based Workflow vs Direct Collaboration
Not every GitHub project requires contributors to fork the repository.
Some teams give developers write access to a shared repository. Those developers can create branches directly inside that repository.
| Area | Fork-based workflow | Shared repository workflow |
|---|---|---|
| Repository access | Contributor works from a separate fork. | Contributor has access to the shared repository. |
| Feature branch | Created in the contributor's fork. | Created in the shared repository. |
| Push destination | Usually the contributor's origin. | Usually the shared repository's remote. |
| Pull request | From the fork to the original repository. | From one branch to another in the same repository. |
| Typical use | Open-source contributions and external contributors. | Internal teams and trusted collaborators. |
11. Common Mistakes and Best Practices
Common mistakes
- Confusing origin and upstream: Remember that origin normally points to your fork in this workflow.
- Working directly on main: Create a feature branch for each contribution.
- Forgetting to fetch upstream: Your local branch may be behind the original project.
- Opening a pull request in the wrong direction: Check the base repository and compare repository.
- Committing unrelated files: Review
git statusandgit diffbefore committing. - Ignoring project guidelines: Read the contribution guide and follow the project's testing requirements.
- Force pushing shared branches: Rewriting shared history can disrupt other contributors.
- Leaving conflicts unresolved: Always remove conflict markers and test the final code.
Recommended practices
- Read the repository's README and contribution guidelines first.
- Check existing issues before starting a contribution.
- Use descriptive branch names.
- Keep commits focused and meaningful.
- Write clear commit messages.
- Test your changes before opening a pull request.
- Explain the problem and solution in the pull request description.
- Respond respectfully to reviewer feedback.
- Keep your fork synchronised with upstream.
- Never commit passwords, API keys, tokens, or private configuration.
12. Real-World Production Considerations
Fork-based collaboration is not only about Git commands. It is also about protecting the quality and security of a software project.
Protect the main branch
Important repositories should protect their main branch. Rules can require pull requests, approvals, and successful status checks before merging.
Automate validation
Use CI pipelines to build the application and run automated tests. This helps catch problems before changes reach the main branch.
Protect credentials
Never include production secrets in commits. Use appropriate secret management and GitHub's security features.
Keep contributions traceable
Use meaningful commits and link pull requests to related issues. This helps maintain a clear history of why a change was introduced.
Respect repository ownership
Follow the project's licence and contribution policy. A fork does not remove the original project's licence requirements.
13. Interview Questions and Answers
Q1. What is a fork in GitHub?
A fork is a GitHub-hosted copy of another repository under your account or organisation. It lets you develop changes separately from the original project.
Q2. What is the difference between fork and clone?
A fork creates a repository copy on GitHub. A clone downloads a repository into your local machine.
Q3. What is the difference between origin and upstream?
In a fork-based workflow, origin usually points to your fork. Upstream points to the original repository.
Q4. Why do we use git fetch upstream?
It downloads updates from the original repository. It updates remote-tracking references without automatically merging changes into your current branch.
Q5. Does git fetch automatically update my local main branch?
No. Fetch downloads remote updates. You must merge or rebase the fetched branch to update your local branch.
Q6. What is a pull request?
A pull request proposes changes from one branch or repository to another. It supports code review and discussion before merging.
Q7. Can you push directly to an original repository after forking it?
Only if you have the required write permission. A fork alone does not grant write access to the original repository.
Q8. How do you update your fork with the original repository?
Fetch from upstream, merge or rebase the original main branch into your local main branch, and push the updated branch to origin.
Q9. What happens when you push new commits to a pull request branch?
The existing pull request is updated automatically. You normally do not need to create another pull request.
Q10. When should you use merge instead of rebase?
Use merge when you want to preserve the branch history as it happened. Use rebase when a linear history is preferred and rewriting the relevant commits is safe.
Q11. What is a merge conflict?
A merge conflict occurs when Git cannot automatically combine changes. A developer must resolve the conflicting content and complete the operation.
Q12. Why should we create a feature branch?
A feature branch isolates one change from the main development line. It makes reviews, testing, and collaboration easier.
14. Hands-On Practice
Let's practise the complete fork-based workflow using a public repository you are allowed to contribute to.
Exercise 1: Create your fork
- Find a suitable open-source repository.
- Read its README and contribution guidelines.
- Fork the repository into your GitHub account.
Exercise 2: Configure remotes
- Clone your fork to your computer.
- Add the original repository as upstream.
- Run
git remote -v. - Identify which remote points to your fork.
Exercise 3: Create a contribution
- Create a branch named
docs/improve-installation-guide. - Make a small documentation improvement.
- Review your changes using
git diff. - Commit and push the branch.
Exercise 4: Open a pull request
- Open your fork on GitHub.
- Compare your branch with the original repository.
- Verify the base and head branches.
- Write a clear pull request description.
Exercise 5: Synchronise your fork
- Fetch changes from upstream.
- Update your local main branch.
- Push the updated main branch to origin.
15. Conclusion
GitHub collaboration makes it possible for developers to work together across different teams and organisations.
Forking gives contributors their own copy of an existing project. Cloning brings that copy to their local machine. The origin remote points to their fork, while upstream points to the original repository.
Developers create feature branches, make changes, commit their work, and push it to their forks. They then open pull requests so maintainers can review the proposed changes.
Understanding this workflow is an important step towards contributing to open-source projects and working effectively with distributed development teams.