Version Control (Git and GitHub)

What is Version Control?

Version control systems are programs that help to manage large collections of code. They can vary somewhat from one to the next, but at their core, all version control systems share a few things. They all have a repository to store the code for a given project. They all have some systematic method for keeping track of changes in the code from one version to the next. Most allow users to create "branches" of code which can be used to store alternative or experimental implementations. They all have some method of reconciling differences between multiple version, "merging" them into one. After their initial introduction, it became clear that version control systems are an extremely useful tool, and they are now used in nearly every professional programming project today.

What is Git?

Git is currently the most popular version control system. It has support for all the most common version control features, and its widespread use has led to the creation of a number of programs that support and build on its functionality. This includes integration with many other common software development tools, making Git nearly the only reasonable choice for any new development project. For all these reasons, the EVT firmware team uses Git for our version control. 

What is GitHub?

GitHub is an online hosting platform for git repositories. Hosting a git repository online allows multiple people from a team to coordinate and cleanly combine their code. It also makes sharing and collaborating with people outside a single team much easier, which makes it perfect for open source projects. More important for our team, GitHub also provides a very well-designed graphical system for code review. This allows multiple users on a team to look over one person's changes, leave comments, and ask questions, ensuring all the code in our repository is as good as it can be.

Git and GitHub Setup

1. Set up Git

   1. Download the latest version for your OS from the official Git website.

   2. If not done automatically, make sure you add the path to Git to your PATH variable.

2. Set up GitHub

   1. Create a profile on the GitHub website.

   2. Follow the team's repositories on EVT's GitHub page.

   3. Talk to the firmware lead to get your account added as a member of the RIT-EVT organization.

Using Git

Git is a very powerful and complex system, which will take a long time to master, but you only need to know a small fraction of the commands to use it effectively.  Some of the most basic commands that you should have an idea of how to use are:

• git clone [url]- Make a local repository as a copy of a remote repository at the given URL

• git branch [branch-name]- Create a branch called branch-name off of the current branch

• git commit - Commit local changes to the local repository

• git push - Push local commits to the remote repository

• git pull - Pull remote commits to the local repository

• git diff - View the differences between the working copy and the last commit 

• git reset --hard [commit]- Revert code to the given commit

• More useful commands can be found on this cheat sheet.

Although internally, these are always the commands that will be run, you do have the option of using mediums other than the command line. Specifically, GitHub provides a desktop GUI, and many modern IDEs provide built-in support or plug-ins to expose Git functionality with simple UI elements. This can make using and learning Git significantly easier, especially for those who are unfamiliar with the command line.

Using GitHub

GitHub does a lot of work for us in the background to make the our work easier, but there are only a few occasions that we actually have to go to the GitHub website to interact with it directly. The most common reason for us to do this is for Pull Requests (PRs). PRs are the system we use to peer review code before we put it into the main branch for wider use by the rest of the team. You can read more on when and why we use PRs in our Documentation and Organization Standards. These are the steps for making a PR:

1. Create a branch, and make some commits to accomplish the goal of that branch.

2. Go to the GitHub URL for the repository you want to make a PR for, normally github.com/RIT-EVT/[repo-name].

3. Go to the branches page for this repository.

4. Find your branch, and click "New pull request" on the right side.

5. Title your PR with a pun (look at old PRs for examples), and write a brief description of what was changed in your branch.

6. Click "Reviewers" at the top of the right column and request a review from the appropriate group, such as RIT-EVT/embedded

7. Click "Create pull request," and send a link to the PR in the firmware Slack channel to notify the team that there's a new PR to review.

8. If other members request changes or add comments, you can return to this page to view their comments and respond.

   1. If changes are requested, you should address the requests with new commits and hit the refresh icon next to the requester's name to re-request review.

9. Once there are no more changes requested, you should merge the branch into main and delete it, using the buttons on the bottom of this same page.

If you aren't making a PR yourself but want to review another member's PR, you can follow the steps below:

1. Go to the PR's GitHub page, normally github.com/RIT_EVT/[repo-name]/pull/[PR-number].

2. Look through the Conversation tab to see if there are any current conversations going on that you might want to add to.

3. Navigate to the Files changed tab, and begin looking over the PR's changes.

   1. Even for large PRs, it is best to try to look over every line that has been changed, even documentation, to make sure there are as few errors as possible.

   2. As you go through each file, be sure to mark them each as Viewed to keep track of your progress.

   3. Add comments wherever you have a question or comment about the PR's changes by hovering over the code and hitting the blue plus button.

4. Once you're satisfied with your review, click "Finish your review," and choose whether you want to Comment, Approve, or Request Changes.

5. Even after you've submitted your review, especially if you requested changes, make sure to check back in on the PR regularly to continue conversations and re-review as necessary.