GitHub, for Liquids and the club in general, is a cloud-based web platform and hosting service that we use to keep track of all the code we write for our projects. It uses Git, a version control system that tracks file changes and project history over time. It also allows multiple people to work on and edit a project concurrently without the fear of their work interfering with one another's. The “hub” aspect of GitHub is that it allows users to see other people's projects and “pull” them so they can work and collaborate remotely.
First, you have to make an account if you haven't already. To do this, go to https://github.com/ and register with a valid email address or Google account. GitHub now requires users to register with 2FA, so a valid phone number or email address (separate from the one you are registering with) is needed. With your new account, you’ll have to make a username for yourself. It can be whatever you wish; however, please ensure it complies with the university's online usage guidelines.
After this, you should be redirected to your profile-specific homepage. Here is where you can find all the current repositories that you have contributed to. Repositories (or ‘repos’) are like the general folders that hold the content of your project. In order to access a project, you need access to the repository, either by creating it yourself or by cloning the repository. Cloning is the act of making a copy of a repository’s files and then saving a version of that copy locally on the device you cloned it to, like your home PC or laptop. For STARR, the way you get access to all of the club’s repos is by being added to the private GitHub organization, which is just a collection of all our created repos in one spot. TO BE ADDED TO A REPO OR THE ORG, ASK YOUR TEAM LEAD OR PROJECT LEAD TO ADD YOU!!! With that said, once you are added to the organization and there is a project you’re ready to work on, there are multiple ways you can go about cloning the repository. To start, click on the repository you wish to work on.
As stated earlier, repos hold the projects you work on. Here is an example repo. From this screen, there are a few things worth noting. First, by the repo name in the center, you’ll see a private tag. This indicates that the repo is not publicly visible; in other words, it’s invite-only. The other tag that can appear is “public,” but we only use that if we plan to mass-release something as part of a deliverable. The people who have access to a repo will be listed as contributors near the bottom right. If you ever need to track people down regarding what they added or removed, you’ll know whom to ask. As a housekeeping rule, PUT YOUR GIT USERNAME IN YOUR SLACK SO PEOPLE KNOW WHO TO LOOK FOR!!! This helps us avoid delays caused by not knowing whom to ask.
In the middle of the screen is the file directory, which is a hierarchy of the subdirectories and files contained within the project. A directory is the proper term for a folder or bundle. This display shows how the files will be laid out if you clone the repo, as well as any user-added descriptions and the last modification date. On the website, you can freely open, explore, and view the information in the displayed subdirectories or files; however, editing them is limited. Hidden files start with the “.” character, like .gitignore, which can be set up to track only certain files.
Below this is the README. As the name suggests, it’s usually the first thing you want to read when accessing a new repo. It contains a general overview of the project, key design decisions, important considerations for running the code, and any accreditation or copyright policies set by the key contributors. WHEN YOU ARE WORKING ON THE PROJECT, ALWAYS TRY TO KEEP THE README UP TO DATE so that anybody new to the project can be gently eased into how it works. This will save you time and spare them the hassle of tracking down whom to ask.
Next, there is the main dropdown menu below the repo name in the center. This is an important feature that allows you to preview all the branches the repo has. A branch is a version of the project that is usually distinctly different from another. They all stem from the same base code, but over time, branches may arise because somebody wants to try a new feature that will more than likely break half your code, or because you don’t want every person working on one branch, making the number of pull and push requests more manageable. We’ll talk about those more in depth further down. Still, branches are a useful feature for any Git repo, as they provide a way to segment new feature implementation and add a level of organization that streamlines development.
A common setup is a main branch, one or two feature branches, and a bug-fix branch. Main is the good copy: it is the version that should run out of the box and is the most polished. Your finished project should run off the main branch. A feature branch is where you work on a new feature when you’re unsure whether it will break or worsen the main branch. It should be a place where you can take risks, as this will have no consequences for the final software package if it doesn’t work out. A bug-fix branch is where bugs from main should be addressed. It is useful for larger projects, given the growing interface and logical complexities that come with a larger codebase. You cannot guarantee that fixing one bug will not cause another to arise because of a poor fix.
To implement your changes from one branch in another—for example, when a feature is done testing and ready to be added to main—we use what is called a pull request, as seen in the top left. This means taking the changes from one branch and applying them to another, allowing the recipient to receive the sender’s code. This is formally done by having the developer of the feature branch submit a pull request, along with an explanation of the code and verification tests, to the other contributors. Then, one of the other contributors verifies the code and the reported testing before allowing the merge to happen between the branches. However, it is not always sunshine and rainbows: pull requests can result in what is called a merge conflict, which is Git’s way of saying that the same segment of code has been changed in different ways by both the sender and the recipient. To resolve the conflict, it is up to the pull request reviewer to decide which version of the code takes priority. This requires you to understand the code you’re working with, so be ready to backtrack a lot. Also, don’t approve your own pull request; it’s like laughing at your own joke—you have to be really good at what you do to pull it off.
Lastly, on this page is the green button that says “Code.” This is how you clone repositories by command. However, there are a few methods for doing so. In this tutorial we’ll go over the method of SSH further down for those who wish to do it.
To make a repo is pretty simple first navigate to your profile in the top right corner
