The Ultimate Guide to Git for Open-Source Development

Initial Process

To develop an open-source project, we must first Fork the Repository, as it is not our own project, and we dont have write access.

Once we fork the repository, an identical copy will appear under our account. We usually refer to the original project as the upstream repo and the forked copy as the downstream repo.

Since we have write access to the forked repository, the first step is to clone it. Note that we should clone our forked repo, not the upstream repo.

For example, if you want to contribute to the kuberay project, and our GitHub username is MortalHappiness, the URL of the upstream repo would be https://github.com/ray-project/kuberay.git, and the URL of our forked repo should be git@github.com:MortalHappiness/kuberay.git (SSH) or https://github.com/MortalHappiness/kuberay.git (HTTPS). Let's assume we are using SSH.

After cloning, we can run git remote -v, and it should look something like this:

origin  git@github.com:MortalHappiness/kuberay.git (fetch)
origin  git@github.com:MortalHappiness/kuberay.git (push)

Next, we need to add the upstream remote by executing the following commands:

git remote add upstream https://github.com/ray-project/kuberay.git
git remote set-url --push upstream no_push

In the above commands, replace the URL in the first line with the upstream URL of the project you want to contribute to. The second line is to prevent us from accidentally pushing to the upstream repo. (Although we dont have write access and cant push, if one day we become a committer with write access, this line helps avoid accidentally pushing to the upstream.)

Run git remote -v again, and it should look like this:

origin  git@github.com:MortalHappiness/kuberay.git (fetch)
origin  git@github.com:MortalHappiness/kuberay.git (push)
upstream        https://github.com/ray-project/kuberay.git (fetch)
upstream        no_push (push)

The following is my personal habit and is not necessarily required. To avoid accidentally developing features on the master branch (or main branch), I create a local branch to track the upstream/master branch and then delete the local master branch.

git fetch upstream
git checkout -b upstream-master upstream/master
git branch -d master

If you're using the GitHub CLI, you can also set the default repo to upstream.

gh repo set-default https://github.com/ray-project/kuberay.git

Remember to replace the URL in the above command with your upstream URL.

Developing New Features

Ensure that our local upstream-master branch is in sync with the remote:

git checkout upstream-mastergit pull upstream master

Check out a new branch, lets say feature/example:

git checkout -b feature/example upstream-master

Proceed with normal development (add, commit, push).

Go to the upstream repo to open a pull request.

Syncing Upstream

If we are in the middle of development and the upstream repo has new commits, we need to sync with the upstream by running git pull upstream master.

Sign-Off Commits

Some open-source projects require that every commit be signed off, meaning we need to add the -s flag when executing git commit, making it git commit -s. This will add a Signed-off-by line at the end of the commit message. So, the commit message will look like this:

Some commit message.

Signed-off-by: Chi-Sheng Liu <chishengliu@chishengliu.com>

If you forget to add the -s flag when committing, you can follow this guide to remedy it.

If you find it cumbersome to add the -s flag every time, you can use a commit-msg hook:

Write the content above into .git/hooks/commit-msg and then execute chmod +x .git/hooks/commit-msg to make it executable.