Problem Statement

In class, computer science (CS) students become very proficient with coding and problem solving. But as students transition from university into their professional careers, or as even coursework becomes more online and digital, it is becoming increasingly important that they understand not just how to write software, but how to develop in an organized way and coordinate with others. The purpose of this guide is to provide a document that teaches students these practices and, specifically, how to use the most important and common tools for this in industry.

Specifically, this guide will include how to set up meetings and project management tools such as:

• Trello to promote easy and clear development

• Visual Studio Code (VS Code) which promotes remote development through some extensions

• Git with GitHub to promote remote development through version control

All of this will culminate in a document that CS students can use whenever they are working remotely and are working in groups. The organization method would be a user document, that goes into detail on our three applications for CS students. We will split each application into its own parts that go into how they could help CS students working remotely, and show how each is used to augment the development process.

Background of Problem

These applications enable users to perform tasks beyond just writing code - such as version control and team collaboration - they have become not just common, but ubiquitous in industry. We selected Trello, VS Code, and GitHub since they are often used in industry:

Yet students do not really learn these aspects of project management and team software development in class, so they inevitably have to get “up to speed” with them when they finish school and pursue careers in industry.

The Kanban Board technique is a visual depiction of work when it has various stages of development. The Board has two main properties: Cards and Lists. Using these two properties to your advantage will allow you to know exactly what you need to do, what you are doing now, and what has been done in a visually simple way!

Cards

Lists

Kanban Board Lists are used as columns for the cards to reside in, they are supposed to represent a flow from left to right for your development process. Depending on your workflow the name of your lists can change, but in most cases on the right side there is a done pool, so then the users can visually see all the work that has been done. It gives the team a visual reinforcement that when you finish a card it can go into the Done list. For lists before hand it's up to your imagination, for our Trello Template we have the following lists:

This section will teach the user how to use Trello to create a board for their future remote development projects. Throughout this section we'll go over the following:

• What is the Kanban Board technique and how Trello uses it to its advantage

• How to start up a Trello Board

• How to utilize Lists in a Trello Board

• How to utilize Cards in a Trello Board

By the end of the section we hope you can utilize our Trello Template to make your own Trello Board just like the one we made below

Problem Statement

Trello helps teams work more collaboratively and get more done

As CS students, many classes prioritize team projects to simulate the software engineering world. We see this in classes such as:

• CS 3110: Data Structures and Functional Programming

• CS 3152: Introduction to Computer Game Development

These classes are all wonderful in simulating the amount of coding teamwork that goes into the software engineering world at many of the forefront companies like Facebook and Google. But these classes fail to teach good practices in keeping up productivity within your team and making sure the tasks are done quickly and are split up evenly by the whole team. These are skills that are essential for software engineering jobs, and we hope to fill that gap.

Background: Project Management With Kanban

Constraints

Trello has multiple pricing tiers including a well rounded free option

Tier 1: Free Option

Using this option you can make as many teams as you would like, and within each team you can make up to 10 kanban boards. Within a kanban board, the user should be able to make an unlimited amount of cards and list, meaning the possibilities will be endless with the work you can achieve with one board. The one main caveat is there is a limit of 10 megabytes per file attachment to a card. This means you can't really upload your code to each card, but if you couple Trello with our Code management recommendation, Github, this shouldn't be an issue.

With the free option the user also gets access to 1 power-up per board. Power-ups are how you use third party applications such as Google Calendar and Slack in association with your board. Power ups aren't needed for how we recommend a student to use Trello, but if you want to become a more advanced Trello user, power ups are a great avenue.

This also rings true with the automation that Trello possesses, for most cases a user can advance the progress of a board and you don't need to setup automation to achieve that. If you would like to become a more advanced Trello user the free option allows for:

• 50 command runs each month

• Commands can only be limited to simple automation tasks

Overall, Trello's free option has everything you would need to ensure good project management practices for a CS student, but also has the power ups and automation for a user to grow into a more advanced Trello Board Maker. The other options are nice, but are mainly for businesses.

Other Tiers

Scope

The Trello section won't however go over power-ups and automation on Trello as we don't believe these tools are essential to the amazing collaborative project management Trello achieves. Once you are done with this section and become a beginner Trello user, feel free to be more advanced and use automation and power-ups to your advantage.

Set up your Account

Make a Team

Once you have an account you can make a team with all of your teammates.

Find this section of the homepage below, here you can add a new team

Now make a team name, choose a team type, and add your team members!

Make a Trello Board using our Trello Template

Find the More Button on the right panel

Now click The Copy Board Button to copy our template for your team. Once that is done you can freely edit and add your own cards or even your own lists.

The next section will go into more detail of the template and how Trello Lists work.

What are Trello Lists?

A Kanban Board List that houses Trello Cards

Trello Lists aren't that much different from Kanban Board Lists, they follow the same form as Kanban Board Lists. In our template we have provided the main 5 lists we believe you need for remote CS projects, but at the end of the kanban board there is always a button to add another as the number of lists can truly be infinite on Trello.

What are Trello Cards

A powered-up Kanban Board Card that allows a ton of extra functionality

Trello Cards at its simplest is a sticky note, but at its most advanced it is very powerful. You can add another card to a list by clicking this button here. This brings up a view that allows you to add a quick title, and upon hitting the options you can members and labels to the card, both of which add much functionality.

Trello cards also open up a whole view upon clicking one where you can be as detailed as possible with your card. Having this extra functionality is daunting at first, but once you get the hang of it, you can take a close look at every task you have to do and have a good understanding of the problem at hand.

Members

The ability to assign cards to your teammates

The members field of a card is where you can assign to someone a card. This is really nice for delegating work when you're a project leader, or assigning who you would like to review your card. Once you add a member you will see their Profile picture in the minimized view of the card. This makes it really simple to see who has to work on what whenever you glance at your Trello Board. Below is how to add members to a card.

Labels

The ability to add labels with a color and a title to a card that could mean anything your team would like

Labels are a very powerful feature of cards. These labels have to main parameters: color and name. You could assign one of 10 colors to a label, and assign any name you would like. Labels can represent a myriad of features, such as:

Priority

Delegating how cards should be prioritized with the label feature

Using your labels as differing priorities are very helpful as your team can easily understand what tasks can be done first, and what tasks aren't that needed. Prioritizing work also increases productivity in a lot of ways as it forces you to work on the highest priority tasks, and then move on to the smaller ones. These priority labels could be as follows:

Work Time

Showing how much time a card would take to implement with labels

When struggling with what work you would like to work on it might help for your team to use labels as estimates to how long they need to implement. If it's a simple feature you can add a label of with a short time or if it's a big feature add one with a long time. Here's an example below:

Kind of Work

Splitting cards into categories to differentiate the kind of work it is

When your project extends many mediums it might be helpful to add labels that represent the different mediums. An example of this could be:

Descriptions

When describing your card you can take advantage of the Markdown support trello has to make detailed descriptions of what you have to do. When moving through the development process it is also helpful to add instructions on how you can test the work for the card so other members can look through and test the work you have done.

Checklists

You can add checklists to your cards to work as sub tasks for them. This is great to show how much progress you have made on a task, and an easy way to update the card with more subtasks. For Trello Cards, you can add multiple checklists and you're always able to add more sub tasks to a card.

Other Features

• Due Date - To denote when a card should be done by

• Commenting - To quickly add supplement information or question someone else's work

Problem Statement

Learning these tools will then surely cause a palpable boost in productivity to be seen.

Background: What is Visual Studio Code?

Constraints

Both VS Code and Live Share are completely and totally free. There are no costs whatsoever associated with using them assuming you already have a computer of running Windows, Linux or macOS.

Scope

What are Trello Lists?

A Kanban Board List that houses Trello Cards

Trello Lists aren't that much different from Kanban Board Lists, they follow the same form as Kanban Board Lists. In our template we have provided the main 5 lists we believe you need for remote CS projects, but at the end of the kanban board there is always a button to add another as the number of lists can truly be infinite on Trello.

Lists We Recommend for Project Management

In our Trello Template we have the following lists that all should help visualize the development process and split up all the cards your team makes.

Backlog

A list of cards your team doesn't necessarily need to work on right now

A backlog list is supposed to house all of your cards that aren't necessary for project completion at this moment, but can be done sometime in the future. Cards in this list can be added if they're features that you dream on working on, or features that you don't need to think about for a while.

To Do

A list of cards your team needs to start working on soon

Cards in the To Do list are tasks your team should be getting on as soon as they can. Once a member finishes a task in the Doing section they should just quickly grab a task from the To Do pile. Make sure this list doesn't get too long, so the work for your team doesn't seem too daunting.

Doing

A list of cards your team is actively working on

These are a list of cards that members are actively working on, if the cards are made correctly you can quickly see who is working on what. This list is great to check on team members if they are doing the work they're supposed to.

Code Review

A list of cards your team is actively reviewing

Code review is an optional but recommended list as when a card is done being worked another member can then review the work done in relation to the card. This is really nice for large projects where you might not have much overlap between each other's work.

Done

A list of all the cards you have finished

Once you are done reviewing a task they go into the amazing Done list that is a memory of all the lists you have done. When you are done with a project it is really nice as a team to go through everything you have done to remind yourself of the amount of work you had to do.

Live Share can come in handy in a variety of situations.

In the case of students, imagine you’re in a group project with three other students. Unfortunately for your group, the only work that has to be done on the project is within a single file, meaning every member of your group will only interact with that one file. This means that if you were to want to have every member of your team working in the file at the same time to maximize efficiency, the only way your group would be able to keep track and sync the code would be with Git. Unfortunately, many issues might arise because of this such as merge conflicts when you try to sync the code (Which you can check the git section of this document to learn how to navigate) or people working on the wrong section of the code (Which you can check the trello section of this document to learn how to avoid such misunderstandings). Rather than deal with these problems directly, we can just have everyone be able to see the entire document as it’s being typed live. This would mean there would only ever be one live copy of the file, meaning it’s impossible for merge conflicts to occur. It would also be incredibly easy to see if someone is working on the wrong part, as everyone else working on the document will see it being changed live.

Live Share’s utility isn’t limited to just students, it can also be used in workplace settings just as easily for the same reasons as above and more. For example, if a company didn’t want to use Git or some alternative for file hosting, perhaps out of confidentiality concerns, they could instead just have one copy of whatever project they are working on that everyone interacts directly with through Live Share. This would ensure the only place the files are hosted is on a computer the workplace should already trust.

Live Share

Live Share is an extension made by Microsoft for VS Code for the purposes of furthering collaboration by allowing multiple people to edit and debug code in real time. In other words, multiple people can be working on the same file and can see code being typed live from their own computer no matter where they are. The functionality of Live Share isn’t just limited to typing code at the same time, it can also be used to share debugging sessions, terminal instances, localhost web apps, voice calls and even more. This tool, for the purposes of remote development, is almost invaluable as it allows group projects to function as if everyone working on the project is right next to each other. This functionality has many uses for both the workplace and school work, you can find some examples of this in the next section. An example of how Live Sharing appears while using it can be seen in the image below.

The functionality of Live Share isn’t just limited to typing code at the same time, it can also be used to share debugging sessions, terminal instances, localhost web apps, voice calls and even more. This tool, for the purposes of remote development, is almost invaluable as it allows group projects to function as if everyone working on the project is right next to each other. This functionality has many uses for both the workplace and school work, you can find some examples of this in the next section.

Installation of Live Share into VS Code is simple, it’s done the same as any other VS Code extension. From the opening window of VS Code, select the extensions page from the left hand side as highlighted in red here:

From there, use the search field at the top to search for “vs live” or “live share”. Then the following should be visible:

For just the base functionality, the first one on the list, “VS Live Share”, suffices. Simply hit the install button on the bottom right of the box containing the first entry. If you wish, you can click anywhere else on the box and more information describing Live Share will appear on the right side of the page. As it says in the figure above, “VS Live Share Audio” allows one to share the audio of the host computer through the extension. This may or may not be desired and should be installed if that’s a feature you’ll want while working. The “VS Live Share Extension Pack” includes both “VS Live Share” itself and “VS Live Share Audio.” In other words, it just gets the other two mentioned extensions and bundles them into one installation. From there you’re done and you have the functionality installed.

Usage is extremely easy. You should now see a “Live Share” Button on the status bar of the bottom of your VS Code. Follow these instructions in order:

Click on this button (You can also access this with the command Ctrl+Shift+P / Cmd+Shift+P depending on your operating system). A pop-up will appear asking you to sign-in which you’ll complete in your browser. If you don’t have an account then you’ll be prompted to create one. Once you’re done following the instructions, you can just close your browser.

After you’re signed in you’ll see a new option on the VS Code activity tab as highlighted in red. To share a project, open the folder as you normally would (File -> Open..).

To collaborate, now click the “Live Share” button in the bottom status bar then select "Live Share: Start a collaboration session".

This will cause an invite link to be copied to your clipboard. An option to make the link read-only will also appear, which you can select if that’s desired. To share with other people, just send them this link via whatever way you normally message them. Make sure not to only send this link to people you trust, you don’t want to expose your files to random people. When someone attempts to join you’ll be prompted if you want to let them join or not.

That’s all it takes. From there you’ll be collaborating live! All participants will be able to see code as it’s being typed live. Each participant will see the folder being worked on as if it was on their own computer. This is an introduction to Live Share, there’s more functionality to it than explained in this document but this was just supposed to serve as an accessible guide on how to get started.

To end the session, hit this button in the top right:

If you want to join a session, just click the link the host sends you. It’s as simple as that.

Problem Statement

Scope

There is a lot you can do with Git and GitHub but the basic workflow with GitHub is to create a remote repository with GitHub, sync that repository to a local workspace, and commit changes made locally back to the remote repository. This section gives instructions on how to perform this basic workflow and a high level view of the process.

Constraints

Git is entirely free, and while there are paid versions of GitHub, all the actions in this user document can be done with the free version of GitHub.

Background: Version Control, Git, and GitHub

Version control systems are tools that enable developers to work in parallel over shared projects and to synchronize changes that are made in parallel [11]. With version control, developers can collaborate asynchronously. When working as part of large or distributed teams on complex projects, asynchronous collaboration is a necessity. Consequently, version control has become an important tool in the development cycle in industry and academia [11].

Git is a free open source version control system that can store all files and their version history locally, eliminating the need for a central server [12]. Git can be paired with GitHub, a free hosting service for Git repositories, in order to be used for collaborative software development. With Git and GitHub, developers can keep a remote version of their source code which others can download and edit asynchronously. Git and GitHub are not the only tools for version control, but with over 14 million registered users and 35 million repositories, Git and GitHub form one of the most widely used version control paradigms [12].

Creating an Empty Repo

On the GitHub home page navigate to “+” at the top right of the page and click “new repository”

Set the owner of the repository from the drop down under the owner field and name the repository. The owner can be your own user account or an organization if your account is linked to any team/organization.

On the same page, set the repository access to public or private. This sets the read access for the repository. Public repositories can be read by anyone on the internet while private repositories can only be accessed by users or organizations you explicitly share the repository with. For both visibility modes, you choose who can commit to the repository.

(optional) Add a README file. README files are Markdown files that describe what your repository does and how to use it. Clicking the “Add a README file” box initializes your repository with an empty README file. The contents of README files will be displayed on the code section of the repository page.

(optional) Add a .gitignore file. The .gitignore file lists all the files that you don’t want to track the version history of. Under the “Add .gitignore” there is a drop down of templates for the .gitignore file for different industry practices or best practices for different languages.

(optional) Choose a license. You can initialize your project with a software license that defines what is fair use of your software. Under the “Choose a license” there is a drop down of software licenses that you can choose from.

Finally, click “create repository” at the bottom of the page.

Create a Repo from an Existing Project

$ cd [local_project] 
# initialize empty repository in .git directory
$ git init 
# Track all files in the project
$ git add --all 
$ git add LICENSE
# commit tracked files to the repository
$ git commit -m "first commit" 

These commands create a local Git repository and stage all the files in the workspace to be added to the empty remote workspace. To link this local workspace to the empty remote repository, you need an HTTPS link to your remote repository. To copy this https link:

1. Click on the "code" section on the GitHub repository page

2. Click on the “code” button

3. Click on “HTTPS”

4. Click the clipboard icon

Next, enter the following commands in a command shell:

$ cd [local_project]
#add a new remote
$ git remote add origin [your https link] 
#verify the new remote
$ git remote -v 
#push committed changes to repo
$ git push -u origin master 

These commands add a new remote for the empty repository and then push all the staged changes in the local Git repository to the remote repository.

Repository Visibility

1. Click “settings” on your repository’s GitHub page

2. Click "Options" from the sidebar

3. Scroll down to "Danger Zone" section

4. Click "Change Visibility"

Collaborators

You can explicitly invite users to commit changes to your repository through adding collaborators:

1. On the repository page navigate to “settings”

2. Click “Manage access”

3. Click “invite collaborators” and type in the user name of the users you want to add.

This section will teach the user to use a feature known as branching to manage multiple parallel "copies" of the codebase by guiding them through steps of a tutorial. It will also explain how using branches can improve project organization when there is a large codebase with lots of independent work being done on it.

Problem Statement

Because pulling and pushing code to one revision log requires synchronization (local repo must be up to date before pushing, other developers can push conflicting code - that which modified other code your work is based on), working with a singular log of revisions becomes difficult. This is true even when different coders are working on unrelated pieces of code, which leads to inefficiency when developers want to work asynchronously and are constantly creating conflicts. Developers need a tool to work asynchronously on the same codebase by deferring conflicts/inconsistencies in their changes to a time of their choice later.

Background: Managing Complex Codebases

In more complex projects, Git is not only used as a revision control tool, but also an organizational tool for when development is happening in multiple places, across different sub-teams, at the same time.

Git addresses this problem through a feature known as branching. Branching allows developers to take copies of a set of revisions (thus creating a branch), and work on them separately, committing different code to copies of the codebase. Then, through a process called merging, the additions in each branch can be combined later, thus avoiding workflow interruptions from conflicts along the way.

Allowing developers to defer/avoid code conflicts that interrupt their workflow when working independently is not the only benefit; Branching opens the doors for a wide variety of practices that create a more organized and reliable codebase. For example, branches allow developers to:

• Code independently based on the same codebase, without conflicts caused by being forced to pull each other’s potentially unrelated work

• Store experimental or buggy code somewhere else for testing purposes, but still tracked by revision control

• Group independent changes by feature to keep different pieces of work-in-progress code organized without interfering bugs/issues across different sub-projects

These are the benefits we hope you can leverage after learning to use branches in Git.

Constraints

Branching and merging are features are built into Git so there are no limitations in terms of using them.

Scope

This section focuses on branching and branching-related features. There are other features for codebase management and branch management such as rebasing and submodules, but branching is the most commonly used, and other the other features are quite advanced and have many pitfalls. Understanding branching and merging is sufficient for being able to manage complex codebases, as they already allow for asynchronous development and combination of code. Because teaching this kind of codebase management is the purpose of the document, and because this section is intended as a beginner-level tutorial, rebasing, submodules, and other features are not within the scope of this document.

Unless you created a repository from an existing local directory, The GitHub repositories created in previous sections are purely remote repositories. To sync these remote repositories with a local workspace you can clone your repository into a local directory. Once you clone your repository into a workspace, you can add changes on your local machine and then push them to your remote repository.

Clone Repository

To clone your repository you first need an HTTPS link. If your repository is empty you can copy this from the top of your repository page.

If the repository is not empty, you can copy the HTTPS link by:

1. Clicking on the "code" section on the GitHub repository page

2. Clicking “code” button

3. Clicking “HTTPS”

4. Clicking the clipboard icon

In the command line enter the following:

$ cd [your_local_workspace]
$ git clone [HTTPS link]

Now your remote repository is synced to your local workspace. All changes that are explicitly committed and pushed will be added to the remote repository.

Pushing Local Changes

To push local changes in your cloned repository to the current branch, enter the following commands in your cloned repository:

$ git add --all
$ git commit -m "your commit message"
$ git push

Updating the Local Workspace

When collaborating with others, you should always make sure you are working with the latest version of the repository before making local changes. To update your local workspace to the latest commit of the remote repository, enter the following command in your local workspace directory:

$ git pull

Before we begin, a more technical introduction to branching and merging is necessary to introduce some concepts, terminology, and conventions.

Branches

Branches are where code and revisions are committed and pushed to. In a repo, by default, any work done is done on the default “master” (sometimes called “main”) branch. New branches are created as copies of other “source” branches, that is, when a new branch is created from a source branch, everything – all files, content, and revision history - in the source branch is copied to the new branch. From then on, commits and changes are managed independently in both branches and do not affect each other, and developers can choose what branch to push their changes to. For example, if branch B is created from branch A, one can commit code to branch B, and nothing will change in the copy of the codebase stored in branch A.

Merging

Merging allows one to combine two branches, transferring the changes from a branch (again called the source branch) to another branch (called the destination branch). In doing this, all differences in revisions between the source and destination are committed to the destination branch. Sometimes, there are conflicts, where both branches made changes to the same code, in which case the user is required to resolve the conflicts in a so-called merge commit where the user picks what code from each branch should be incorporated (or writes their own code so that both sets of changes can work together).

Now, we will dive into the details of creating, managing, and merging branches. We will walk the user through the following:

• Creating branches

• Switching to a branch to make a change

• Merging a branch

• Resolving simple conflicts when merging code

• How GitHub provides an alternate and easy to use GUI for the above tasks

With knowledge of these terms and what - on a more technical level - branches really are, we can begin to demonstrate how to use them.

Navigate to a Git Repo

To get started with branching, point your Git console within a repo, as is necessary for running any Git commands. We will demonstrate these tasks on a new GitHub repository with nothing but the default readme file:

The Revision Tree

Github offers a way to visualize a repository and its branches under insights -> network on the page for your repo. With our initial commit, the tree is quite bare:

As we begin to use branches, we will see how the tree allows us to visually depict how different branches are developed on parallel.

Creating and Switching Branches

Whenever working in Git, you will be working on a particular branch (master by default). To create or switch to a branch, use:

git checkout -b <branch name>

If the “-b” argument is provided and the branch name does not exist, a new branch will be created with that name. Any uncommitted changes on your current branch will be transferred to the new branch. Then, whether the branch already existed or a new one was created, you will be switched to working on that branch.

Now make a new file, with some basic contents, and commit it to the repo. We will use the following example:

Example.txt (example-branch is the branch name we will use)

// Hello World!

Pushing a branch to a remote repo (such as on GitHub) requires a special command if the branch does not exist there yet (otherwise just push normally):

git push --set-upstream origin <branch name>

When this is done, we may view the branch in our repository on GitHub. By using the small dropdown on the top left to select the current branch. First, we notice that our commit and corresponding file are not in the repository by default. This is because we are viewing the main branch and not our new branch. When viewing the new branch, we see that our changes are there.

Now, use the git checkout command to switch back to the main branch. You will notice that any new changes in the branch you created are missing. This is because they are only on that branch! We now make a change here, to demonstrate how the two branches can be developed independently:

Example.txt (main)

// Hola!

Now we may commit this file, and view the revision tree, which will reveal what our repository looks like now with its two branches, each with their own different "code":

As we can see, the two branches are now split from the point we made the new branch, and each has their own commits with different content.

Managing Branches on GitHub

GitHub also provides a user interface on the website for creating and managing branches. By clicking on "branches" next to the branch selection dropdown when viewing the repo, you will be able to view the branches that have been created. Here you can manage and navigate between branches. To delete a branch, click the small trash can icon for the branch you wish to remove.

Returning to the homepage for the repo, typing a non-existent branch name in the branches dropdown and hitting enter will create a new branch from the one currently being viewed.

Recap

In summary, we have learned how to use branches. From this guide you should know how to:

• Push branches to a remote repository

• View them on GitHub

• Add files and code to them independently

• Visualize the revisions and branching history in a tree-like view

• Create and manage branches through GitHub's interface instead of the terminal

Now that you understand the power of branches in Git, it is pretty clear to see not only how they are useful, but also how they may be complicated and easy to trip yourself up over. To get the most out of branching, developers tend to follow these best practices to keep things organized, sidestep error-prone areas of the process, and to manage their projects from a deployment point of view.

Only Keep Working, Production Code in the Main/Master Branch

By doing this, developers can guarantee they have a copy of the codebase that is 100% functional and able to be shipped to clients/users/customers. More than that, this provides a branch where there is known, tested, bug-free code for other branches to be based off of, so that new features being developed do not have irrelevant issues from other work-in-progress code. Some projects go as far as to assign roles to users in the repository, such that only special leaders in the project can approve merge requests into Main/Master, even though everybody is allowed to submit them.

Organize Branches by Feature

This makes logical sense as coding different features, probably independent and having no inter-related code, does not require users to work on the same branch. It also provides a good way to organize what is being worked on within the project. Finally, branches are a great way to keep experimental, possibly broken code that won't be used within the revision control system when being developed, and potentially to be revisited, without affecting the functionality of the main copy of the codebase.

Merge Requests are Code Review Opportunities

Especially when following the above practices, merge requests become times when everyone on a project can view all of the commits and revisions for a particular, complete feature, before deciding to integrate it. This holistic view allows for evaluation of the end result better than doing code reviews commit-by-commit. Then, when merging into Main/Master, the code being merged represents a working piece of specific functionality, approved and tested by the team, with any issues ironed out through the built in issue tracking and commenting/discussion features that developers can use to communicate.

Do Not Merge With Uncommitted Changes

When we wish to combine the changes in two branches. We do this by merging them.

Merging Locally With Command Line

To merge, switch branches to the desired destination branch (we will use main, continuing with our example as before) and run

git merge <source branch name>

If there are so-called conflicts, conflict markers (determined by <<<<<<<, representing the code in current branch, or >>>>>>>, representing the new, conflicting code. They are separated by =======) will be in the files, and the user must resolve all conflicts (make sure to remove the markers, too), making necessary changes to ensure the code from both branches works. Conflicts occur when two branches make changes to the same piece of code, which makes it unclear which to keep or how to combine them.

When this is done, commit your changes. Then you should run:

git merge --continue

and then push your changes to the remote repository. To abort a merge, run:

git merge --abort

In scenarios where there are no conflicts, git merge should work immediately.

Merging With GitHub

Manually resolving conflicts like this is important to know how to do, but can be difficult and time-consuming. GitHub provides an interface for doing this, with an automatic merging algorithm. It will also tell you when things are too complicated for it to figure out, and to complete the merge manually as we have shown above in cases where you absolutely must. But usually, a merge completely on the GitHub UI is possible. In any case, it is always worth creating the so-called "pull request" to merge two branches on GitHub for three reasons:

1. The request will be on GitHub for other coworkers to see, letting them to comment, review the code, and agree with you to merge it before moving forward. Merging is as much a communication tool as it is a code management tool, and leaving a paper trail when you do it is important for the same reasons as using revision control in the first place

2. The aforementioned automatic merging feature is far easier to use than merging manually and locally

3. If you still need or want to merge manually and locally, it is still possible to do so

To execute a merge on GitHub, click on the "Pull Request" button, which will be in a bar under the main navigation bar with the branches dropdown.

This opens the pull request window, where GitHub will notify you if an automatic merge is possible, and for you to name the request and leave a description/comments before submitting with the button on the bottom right:

In our example case, we see that the automatic merge can not be completed. In the pull request window you will be routed to after creating it (or accessible by navigating to the pull requests tab), there will be a button to resolve conflicts, among the other features of the merging UI on GitHub such as commenting, and - ultimately - approval of the request.

To resolve conflicts in GitHub, clicking that button will lead you to a window showing you the conflicts and letting you decide what to do, much like in the manual case. Other hosts for Git (ie. GitLab) may offer a user interface that lets you pick and chose what code from what branch to keep.

In our example here we can resolve the conflict by including the contents of both files:

With no more conflicts, we use the "Mark as Resolved" button on the top right and the "Commit Merge" button that pops up.

It is worth noting that at this point the merge has not been executed, just - whether a commit was created to resolve conflicts or not - that it is ready to be merged. To actually execute the merge, use the "Merge Pull Request" button that should appear once there are no conflicts.

With the merging complete, we may now view how our two example branches have "converged" as our new branch was integrated into main through the merge:

The additional commit on the example branch was the commit where we resolved the merge conflicts.

Recap

In summary, you now know how to combine code in different branches back together, once they are done being worked on. Specifically, we covered:

• Starting the merge process in the command line

• What merge conflicts are

• How to resolve conflicts

• How to complete or abort a merge in the command line

• How to request merges (called "Pull Requests") on GitHub

• How to resolve conflicts that GitHub cannot automatically resolve within the web interface

• How to approve merges on GitHub, thereby executing the desired merge

• What merged branches look like in the revision tree

Now that you know how to use branches, you can be more organized in your coding projects, especially those with more people on them where lots of different work is being done independently.

The branching and merging workflow, while useful, can be quite complicated, even for a Git veteran. Here is a cheat-sheet summarizing everything we have covered so that you can reference it when you need to remember how it all works:

Use Branches To:

• Code independently on a team, with the same codebase

• Store experimental features/buggy code somewhere for testing purposes without causing problems where the working/production code is

• Group independent changes by feature to keep things organized, and selectively merge them into a production codebase (usually on master branch)

• Communicate and organize with others

The Best Practices Are:

• Group commits for features into new branches to keep things organized.

• Make sure source branches are up to date and don’t have issues/bugs of their own

• Maintain a branch with only working/production code

• Delete old and merged branches unless there is a good reason not to

• Prefer to use branching/merging features through GitHub's interface; it's easier and more organized

Command Reference:

• git checkout <branch name> (switch to branch)

• git checkout -b <branch name>(switch to branch, create beforehand if it does not exist. Current uncommitted changes are transferred)

• git merge <source branch name> (merge branch into current branch)

• git merge --continue (after resolving conflicts manually; recommended to do so on GitHub if possible)

• git merge --abort(abort resolving a merge conflict manually)

Additional Resources:

Trello, VS Code with Live share, and Github are amazing tools that allow for great team project management and productivity.

Using all three of these tools in tandem should greatly improve productivity and this guide should serve as a useful tool in learning how to use all of them.

[1] G. Pisoni and M. Hoogeboom, "Investigating effective dynamics of virtual student teams through analysis of Trello boards," 2019 17th International Conference on Emerging eLearning Technologies and Applications (ICETA), Starý Smokovec, Slovakia, 2019, pp. 639-643, doi: 10.1109/ICETA48886.2019.9039972.

[5] G. Pisoni and M. Hoogeboom, "Investigating effective dynamics of virtual student teams through analysis of Trello boards," 2019 17th International Conference on Emerging eLearning Technologies and Applications (ICETA), Starý Smokovec, Slovakia, 2019, pp. 639-643, doi: 10.1109/ICETA48886.2019.9039972.

[6] Yager T. Visual Studio unites seven languages under the .NET flag - Visual Studio.NET topples cross-language barriers so businesses can produce creative code quicker. InfoWorld. 2000;(41). Accessed October 14, 2020.

[7] Maqsood, Junaid & Eshraghi, Iman & Ali, Syed. (2017). Success or Failure Identification for GitHub's Open Source Projects. 145-150. 10.1145/3034950.3034957.

[8] Website down, can't check

[9] S. Amann, S. Proksch, S. Nadi and M. Mezini, "A Study of Visual Studio Usage in Practice," 2016 IEEE 23rd International Conference on Software Analysis, Evolution, and Reengineering (SANER), Suita, 2016, pp. 124-134, doi: 10.1109/SANER.2016.39.

[12] E. Bonakdarian, “Pushing Git & GitHub in undergraduate computer science classes,” J. Comput. Sci. Coll., vol. 32, no. 3, pp. 119–125, Jan. 2017.

Ryan Richardson

Ryan Richardson is a Cornell senior majoring in computer science. This user document has been the semester long group project that is part of the course ENGRC 3500: Engineering Communications. Ryan has mainly worked on the Trello section and compiling everyone's work in Gitbook. He has been a proud user of Trello for 2 years and wanted to ensure more students knew about GitHub as a good avenue.

Brandon Joseph

Brandon Joseph is a Cornell senior majoring in computer science. Brandon mainly worked on the Visual Studio Code section. He wanted to make sure all students working remotely during this unprecedented time take advantage of useful tools such as Trello, GitHub and Live Share in VS Code. He also wanted to make sure the students carried on the knowledge of how to use these tools when they into the workforce, as their usage should all greatly increase productivity.

Christian Polydor

Christian Polydor is a Cornell senior majoring in computer science and engineering physics. Christian mainly worked on the GitHub - Basics section. He wanted to make sure that computer science students gain a working knowledge of version control through GitHub. He also wanted to ensure that computer science students get some exposure to remote development tools that are often used in industry.

Maxwell Anderson

Maxwell Anderson is a Cornell senior majoring in computer science and engineering physics. Maxwell worked on writing about more involved git features such as branching and merging. With his experience building software in industry and in interdisciplinary research projects at Cornell, he is no stranger to the challenges of project and codebase organization. His mission is to get students up to speed with best practices with codebase management and organization using Git, especially when projects in industry tend to have large groups of people working in multiple areas.