dev-guides

GitHub Workflow

This semester we are using Github for distributing and collecting your assignments. This guide will walk you through how you may obtain the skeleton code, keep track of your progress, submit your assignment, and obtain solutions.

Obtaining Skeleton Files

To obtain the skeleton files that we have provided for you, you need to clone your private repository to your local machine. Your repository page should have a link titled “clone or download” – copy the link from there.

For an individual assignment, you may do the following:

$ git clone https://github.com/cs4118-hw/hw<num>-<github-handle>.git

For a group assignment, you may do the following:

$ git clone https://github.com/cs4118-hw/hw<num>-<team-num>-<team-name>.git

You may then move into the homework directory and begin your work.

Keeping Track of Your Work

To keep track of your work, we encourage you to commit your changes incrementally to keep track of your progress. If you have not used Git before, you should learn it quickly. Jae’s 3157 tutorial should get you started.

After you commit, you can push your changes to the master branch of your repository with the following:

$ git push origin master

With group assignments, we recommend that you push work to branches first, and then merge back into master once your group members have reviewed the code. As an example, suppose that you are working on a part of the assignment, you can create a branch separate from master by doing the following:

$ git checkout master
$ git checkout -b <branch-name>

You can then commit your changes, and push to the branch by doing the following:

$ git push origin <branch-name>

This will allow multiple members of the team to work on separate features in parallel. When the feature you are working on is complete, you may then create a pull request to allow your team members to review the code, and finally merge the changes back into master. You can read more about using branches and pull requests from GitHub’s own documentation.

Submission

To hand in your assignment, you will create and push one or more Git tags. Tags point to specific commits in a Git repo’s commit history. Usually they are used to mark release points in a project; in our case, we are using them to mark the completion of (a part of) an assignment. We will specify what you should name your tags in each assignment. For example, HW3 might ask you to push a tag named hw3handin. To create a tag, you should do the following:

$ git tag -a -m "Completed <homework/part>." <tag-name>
$ git push origin master
$ git push origin <tag-name>

You should verify that you are able to see your final commit and your <tag-name> tag on your Github repository page for this assignment.

If you made a mistake and wish to resubmit your assignment, you can do the following:

$ git push --delete origin <tag-name>
$ git tag --delete <tag-name>

You may then repeat the submission process. You are encouraged to resubmit as often as necessary to perfect your submission. As always, your submission should not contain any binary files.

Viewing Solutions

We will also be distributing solutions via GitHub. You will be added to each homework’s skeleton repo as a read-only collaborator, and some time after the homework deadline has passed, we will add a solutions branch to that skeleton repo. You may checkout that branch to view the solution.

The URL for the skeleton repo will simply be (with <num> substituted for the homework number):

https://github.com/cs4118-hw/hw<num>

You can clone this, but especially for the later kernel assignments, this can be huge, and take longer than it really needs to. Instead, you can add it to your own local repo as a remote. First, navigate to your own local repo, and run:

$ git remote add skel https://github.com/cs4118-hw/hw<num>

This will add that URL as a remote named skel.

Remotes are named URLs from which you can fetch and push commits, tags, and branches. This is usually useful for workflows where you pull from one remote (for example, an upstream open source project), and push to another (for example, your own fork on GitHub, from which you can make pull requests). To list your remotes, run:

$ git remote -v

Now that skel is added as a remote, we can fetch the latest commits, and see what branches are on that remote with the following:

$ git fetch skel
$ git branch -a

The -a flag tells the branch command to list all branches, even those on remotes like skel. Once the solutions are released, you should see one called remotes/skel/solutions.

You can check out those solutions to view them with the following command:

$ git checkout remotes/skel/solutions

Now you can look around, modify, and build the solution code.

Backing Up Your Repos

Some time after the end of each semester, we will remove all of your repos (we will tell you when this will take place via the listserv). Before this happens, you may want to back up your repo, so that you have a copy of your hard work!

Backup using GitHub

Since all of the assignment repos we have created for you are private, you should not be able to fork them as you would with a public GitHub repo. Instead, you may import the repo into your own personal GitHub account, using GitHub’s Importer tool:

N.B.: As of January 2019, GitHub has announced that they will be offering unlimited private repos for even their free tier, so you shouldn’t run into issues with having only a limited number of private repos.