GT-How

Github: A Collaborative Endeavor

—

by

clee857
in ,

By Ashmitha Julius Aravind, Adil Farooq, and Christopher Lee

Collaboration on GitHub is trivial when done right, but all too often the best practices and protocols are ignored leading to chaos in the repository, lost code, and dreaded merge conflicts. This guide covers the best practices and what to do when they aren’t followed.

Introduction

This is a guide regarding how to use GitHub in a collaborative manner, rather than simply as cloud storage or version control for your code. This guide will assume that you are already familiar with the basics of Git and GitHub, including how to git commit, push, pull, repository creation, etc., and that you already have a GitHub account and are familiar with the site. This guide will cover how to best work in teams, how to avoid issues and what to do when issues are encountered. Specifically the guide covers best practices for team GitHub repository management and dealing with branches, and how to deal with merging and merge conflicts.

  1. Part 1: Setting Up Your Team on Github
  2. Part 2: Best Practices: Branches and Pull Requests
  3. Part 3: Merge Conflicts
  4. Conclusion

Part 1: Setting Up Your Team on GitHub

  1. Step 1: If you intend to work only with other Georgia Tech students and for an internal audience, use your Georgia Tech Enterprise GitHub account, otherwise use a personal GitHub. The enterprise offers additional benefits (security, IP protection, extra storage, premium features) but it does not allow the addition of non-GT GitHub users to the team or repository. 
  2. Step 2: Next, if your project is small or self-contained, it is best to create and share a single repository. However, if you are working on a larger project it may be better to create an Organization on GitHub and then create your repository within that.
    1. Pro-Tip: assign an individual to create and manage the repository/organization!
  3. Step 3: If you’ve set up an organization, members may have access to a repository owned by the organization (depending on the organization’s rules), but like an independent repository, collaborators can be directly added and given access to the repository.
    1. This is done by navigating, within the repository on GitHub, to Settings > Collaborators > Manage Access, and clicking on Add People. Then you can provide the username, full name, or email of the desired collaborator to invite them. 
    2. Do note that you should not attempt to add users by searching for them in the “Find a collaborator…” search bar. Deceptively, that bar is only used to search amongst existing collaborators.
Displays a three-step walkthrough to add a contributor to your repository.
Steps to add contributors to your repository through the Github organization site.

Part 2: Best Practices: Branches and Pull Requests

  1. Step 1: Most repositories start with a single branch entitled “main” (sometimes “master”). Best practices dictate that each collaborator creates a new branch from main (say, branch “main_collaborator-name”) and pushes their edits to that branch. Furthermore, each individual should be given distinct tasks, i.e. working on separate folders, files, classes, methods, algorithms, etc. 
A diagram of how the process of creating a branch works. This infographic abstracts how commits function in a branch.
A visual guide of operations that can be done on a Git branch.

Pro Tip: If you need a refresher on Git Branching and Merging, check out the official documentation from Git!

Displays the VSCode source control graph, along with a series of merge operations across two branches.
An example of a series of merges through the VSCode source control graph.
  1. Step 2: Periodically, users should push their work to their remote branch on GitHub. When their given task is complete, they should submit a Pull Request on GitHub, essentially requesting that the updates from their branch be added to the main branch. The manager or another assigned individual should handle the resolution of these Pull Requests.
    1. If all has gone well, if users have worked on separate items, GitHub should be able to automatically complete the Pull Request and update of main. 
    2. If not, you most likely have a merge conflict! See Part 3.
  1. Step 3: After the Pull Request has been completed, and once other team members’ updates have been pulled into the main branch, all collaborators should pull the updates from main into their individual branches so they are working with the latest code. This should definitely be an automatic process as the earlier pull request to main should have handled any merge conflicts. Then the process repeats and you keep working on your code!
An infographic that walks through the process of a pull request and changes on the Github interface.
The pull request interface on Github. After reviewing, click “Merge Pull Request” to confirm the merge.

Part 3: Merge Conflicts

This is how a merge conflict may occur between two workspaces.
  1. Step 1: If GitHub is unable to automatically resolve a pull request, this means that the code in the main branch that you are trying to update by pulling in changes from another branch has already been updated from a different branch in a different way. For example:
    1. Original code: System.out.println(“Hello World”);   
    2. Branch 1 code: System.out.println(“Hello Georgia Tech!”);  
    3. Branch 2 code: System.out.println(“Hello Atlanta!”);  
    4. First, Branch 1 is automatically merged into the Main Branch
    5. Then you attempt to merge Branch 2 into the Main Branch
    6. Now, Git can’t treat Branch 2’s version as an update to the Main Branch, because the changes first made by Branch 1 to Main are not accounted for by Branch 2. Git doesn’t know what to do!
Example of a successful pull request
Example of a successful pull request
Two local repositories attempt to push different changes to the same file
Two local repositories attempt to push different changes to the same file
Git does not know which change to proceed with (merge conflict)
Git does not know which change to proceed with (merge conflict)
  1. Step 2: If the main branch pulled branch one’s code in first (or branch two’s, the order doesn’t matter in this scenario), then when GitHub tried to pull branch two’s code in, it doesn’t know whether “Georgia Tech!” or “Atlanta!” is the correct replacement for “World”. There are several different ways to resolve such a situation.

Pro Tip: Check out the official Git documentation on Merging, as well as guides from GitHub and Atlassian!

  1. Step 3: If you’ve set up an organization, members may have access to a repository owned by the organization (depending on the organization’s rules), but like an independent repository, collaborators can be directly added and given access to the repository.
  1. Option 1: The Simplest, Most Powerful, and Most Annoying: Manually Fix It
    Often, you’ll have no recourse but to inspect the code yourself and fix the error. To do this, open the code in your chosen IDE, say VS Code, and attempt to pull the code from the branch into main. VS Code will inform you of the error and open a merge conflict resolution screen which will show you both versions of the code, allowing you to choose one over the other, or combine the two yourself.
A visual of the VSCode interface after selecting a changelist.
Another commit must be made to submit the new changes.
Shows an example of a merge conflict through the VSCode merge interface. There are two changes that need to be resolved.
The user chooses a change-list to proceed with.
An example of a resolved merge conflict.
A resolved merge conflict in VSCode.
  1. Option 2: Force a Branch to Preferred over the other:
    1. On your computer, in the command line / terminal, run the code:
      1. git merge -X <ours/theirs> <source_branch>  
      2. i.e. git merge -X ours branch_one 
    2. If you choose the option “ours” then the main branch’s version will be preferred in the event of a conflict, if “theirs” then the branch being merged will be preferred in case of conflicts.
  2. Option 3: There are actually dozens of further ways to resolve a merge conflict. So if the previous two solutions do not best resolve your specific scenario, Google, StackOverflow, and the world wide web are your best friends!

Conclusion

We hope that this guide has provided you with all the tools you need to collaborate on GitHub, follow best practices, and face any issues that arise. If there is one lesson you should take away, it is that the best way to face merge conflicts is to ensure that they never happen by enforcing strict work on different sections of code on different branches by different team members. 

Sources

Comments

Leave a comment