Forking an open source project in Git is a simple and powerful way to begin making changes and experiment freely without being afraid of breaking things. It is also a great way to contribute back to the community by knowing exactly where your contribution is going and how it is being used.
This guide will teach you how to fork an open source project hosted on a popular code hosting platform. This is not limited to any particular type of code hosting platform but to give one example, this repository is based on Github.com. What you will learn is the following:
Exhaust All Other Options
Communicate your frustrations clearly. Doing this in a private email will help reduce the chance of the core developers/custodians getting defensive.
- Find out how other community members feel. If no-one else agrees with you, there is a good chance your frustrations are misplaced.
- Describe what you feel would be the bast-case outcome, and how it would be a good result for everyone (not just you).
- Do not threaten to fork the project at this point.
- Give the core developers/custodians 2 to 4 weeks to react.
Make some changes and commit them with useful messages
Now you can start writing your code for your awesome new feature, bug fix or maybe just documentation improvement. Keep your commits small and give them useful commit messages that explain why you have made the change as the diff tooling will be able to show what change you have made
Write your code or change the documentation, save the file and in Visual Studio Code or Azure Data Studio you will see that the source control icon has a number on it
Clicking on the icon will show the files that have changes ready
You can write your commit message in the box and click CTRL + ENTER to commit your changes with a message
If you want to do this at the command line, you can use
git status to see which files have changes
You will need to
git add .or
git add .\pathtofile to stage your changes ready for committing and then
git commit -m 'Commit Message' to commit them
Publicly Announce Intent to Fork
Publicly announce your intent to fork the project. Communicate that you have exhausted all other options. Specify the date at which the fork will occur. This date should again be 2-4 weeks into the future.
Create forum threads so that other community members can voice their opinions of the proposed fork. Participate in any discussions that starts up.
In most cases the community members who have pledged to follow the fork will spend the time between the public announcement and the fork date working on materials for the new project, such as the home page.
Push the changes to your repository
You only have the changes that you have made in your local repository on your computer. Now you need to push those changes to Github your remote repository. You can click on the publish icon
You will get a pop-up asking you if you wish to stage your changes. I click
Yes and never
Always so that I can use this prompt as a sanity check that I am doing the right thing
At the command line you can push the branch, if you do that, you will have to tell git where the branch needs to go. If you just type
git push it will helpfully tell you
fatal: The current branch AwesomeNewFeature has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin AwesomeNewFeature
So you will need to use that command
You can see in the bottom left that the icon has changed
and if you read the output of the
git push command you will see what the next step
Communicate Intent Privately
If step 1 fails, in a private email:
- Communicate your disappointment that a mutually beneficial resolution has not been reached
- Communicate that you have no option but to announce an ‘intent to fork’.
- Again give the core developers/custodians 2 to 4 weeks to react.
Create a Pull Request from your repository back to the original one
You can CTRL click the link in the
git push output if you have pushed from the command line or if you visit either you repository or the original repository in your browser you will see that there is a
Compare and Pull Request button
You click that and let GitHub do its magic
and it will create a Pull Request for you ready for you to fill in the required information, ask for reviewers and other options. Once you have done that you can click
Create pull request and wait for the project maintainer to review it and (hopefully) accept it into their project.
If nothing changes before the fork date arrives – fork.
When creating your new project choose a name that is different from the original project.
On your project web site make it clear that this is a fork, and why the fork occurred.
Do not remove the names of developers or copyright notices from any of the source files or documentation. Choose the same license type as the original project.
Make it clear which version or revision or tagged branch was forked.
Many Forks Are Avoided
By following the steps above forks can be avoided. I have been involved in situations that made it to step 2 in this process. In these cases, when the threat of a fork was seen as credible, the custodians of the project started to engage and a mutually beneficial agreement was reached. I am not naming these projects, that was part of the agreement we reached.
Go Ahead – Contribute to an Open Source Project
Hopefully you can now see how easy it is to create a fork of a GitHub repository, clone it to your own machine and contribute. There are many open source projects that you can contribute to.
You can use this process to contribute to the Microsoft Docs for example by clicking on the edit button on any page.
Even though open source projects are designed for community engagement, there sometimes comes a time when forking is the only way to ensure a project will move forward, or to allow it to be used in ways that aren’t possible otherwise. If you’ve considered forking a project, but don’t know where to start, this guide will help walk you through the process.