How to collaborate and work on GitHub as a team or on a open source project?

This article lists down the steps to follow when you start working as part of a team on a project in GitHub.

To start working on a common project or repo, these are the steps to follow:

  • Fork

We have to first fork a copy of the upstream project repository. Forking creates a copy of the repository into your GitHub account.

Upstream/Origin repository: fakeAssBrian/kittyGenerator

Forked repository: meghana-singh/kitttyGenerator

  • Clone

Once forked, you have to clone the forked repository to your local Git. In your local machine (Git bash terminal), do the below:

$ git clone https://github.com/meghana-singh/kittyGenerator.git

  • Remote

Git automatically creates the remote:

$ git remote -v origin https://github.com/meghana-singh/kittyGenerator.git (fetch) origin https://github.com/meghana-singh/kittyGenerator.git (push)

  • Add remote to Upstream repo

To create a remote to the upstream repository: $ git remote add upstream https://github.com/fakeAssBrian/kittyGenerator.git

  • Rename the remote for the fork

To make sure we don’t confuse the origin to be the upstream repo, we can rename the origin remote to fork remote:

$ git remote rename origin fork

$ git remote -v fork https://github.com/meghana-singh/kittyGenerator.git (fetch) fork https://github.com/meghana-singh/kittyGenerator.git (push) upstream https://github.com/fakeAssBrian/kittyGenerator.git (fetch) upstream https://github.com/fakeAssBrian/kittyGenerator.git (push)

Note: Git configuration file: .git/config

  • Git Branch for your changes

Create a branch in Git with a descriptive name and make changes to the files in that branch.

$ git checkout -b add-brazilian-shorthair

  • Add and commit changes

Add and commit changes: $ git add . $ git commit -m “adds Brazilian Shorthair”

  • Push the branch to your repo

Push the branch to your remote fork repo: Never push the master while working in a team!

$ git push fork add-brazilian-shorthair

  • Create Pull request in GitHub

Once the branch is pushed to your GitHub repo, Create a pull request - Pull requests are used for suggesting changes from your fork to the original/upstream repository.

Add the comments to the pull request describing the changes done. Add snapshots to help assist other team members understand the changes you have done.

  • Merge with Upstream

If there are no conflicts with the base branch (upstream master) then the person with write access to the upstream repo does a review and either does a merge or rejects the changes.

If review is rejected then make the right changes in your local git, add, commit and push the branch back to your fork. You don’t have to create a new pull request. New commits get added to the pull request.

If Upstream master has changed after you made changes in local repository

If the upstream master has changed from the time you forked out from the upstream, then you need to merge the upstream master to your local git master and then to your local git branch.

Pull upstream master

$ git checkout master

$ git pull upstream master

Checkout your branch and do the rebase

$ git log

$ git checkout add-brazilian-shorthair

$ git rebase master

Note: Rebase is similar to merge - Rebase is prefered over merge because merge does an extra commit. Rebase preserves the history better by considering the changes to upstream master as prime and then showing the rest of the commits over it even though the master changes were done after your changes.

  • Push changes to your repo

Once rebased with the master, we can push the branch back to your GitHub repo.

$ git push fork add-brazilian-shorthair

The upstream repo owner then approves the changes and merge and squash the pull request changes with the master.

Essentially, the following steps are followed by the team:

Fork (GitHub) -> Clone (Git) -> Branch (Git) -> Add/Commit (Git) -> Push (Git) -> Pull Request (GitHub) -> -> Merge (GitHub) -> Pull (Git) -> And branch and continue.