Category Archives: Teaching Open Source

I wrote this for the ACSE mailing list about year ago and have passed it onto my colleague when they ask about using github for their classroom. At the encouragement of another colleague, David Humphrey (he did a really good talk on git and github for fsoss2015),I’m going to post it to my blog to make it more accessible.

Using git and github for your classes

git is the open source distributed revision control system used by the Linux project. It lets you create a history of all your code. You can send git repository around as zip files if you like.

github is a company that creates a nice place for you to put these repositories into the cloud so that you can much more easily sync and share these repositories without having to set up servers or send around giant archives. It also provides things like access control, issue tracking, wikis, activity graphs and so on. Very handy.

As this post is long, I’ll start with some links for quick reference on where to find/get stuff. After that I have a section specifically for dealing with github, working together and git itself.

About Github

github has 2 types of accounts: individual and organization.
As a teacher, will need to make for yourself an individual account and an organization account. Any individual account can belong to zero or more organizations. For myself, I have quite a few different organization accounts. One for each of my courses and one for my research group.

It should be noted that both types of accounts are free to use if your repositories are open source. I have been using github as a place to put my in-class examples for students…and that is open source so I don’t have to pay for doing that…you can check out the repo for my data structures and algorithms course here. I use the repository itself for code examples, the wiki for assignments and course documents (minus the notes… I prefer gitbooks for that). I have not yet tried to do this consistently but I think the issue tracker in this case can also serve as a notification and discussion board. You can check out the repo here:

Typically they will want info about your school, number of students and so on. The number of private repositories depends on how many students and how you plan to use the repositories. So for example, if you have 20 students and they work in groups of 4, then you will need 5 private repositories. However, if you have 20 students and they are working individually you will want 20 private repositories. If you want both team and individual repos for some group work and some individual work, then you would need 25. I also suggest asking for a couple of extras for yourself or for class material that you don’t want to open source. In any case what you want to do is set it up so that your organization can have some number of private repositories that will suit your needs.

Aside from you setting up an account, your students must each individually create a github account. Once that is done, have them send you their github ids. They can get a free one. They don’t need to pay for it as the private repos will be given to them through the your organization account.

Once you have created your organization, you can go to your organization settings and create teams. A team consist of 1 or more individual. As the administrator of the organization you will be able to see all the repos so if you forget to add yourself its no big deal. Each team also has different access permissions. Typically I would set up a student team for write access but not admin access. If you are only planning on doing group work then set up each team so that all members are part of that group. If you plan to do individual work or a mix of team and individual work then you will want to set up a team for each student.

Once you have the teams set, you can then create private repositories. You can initialize them with an empty readme (or push some code up by following the instructions). In any case once you have created those repos, you can give access to 1 or more “teams” by hitting the collaborator button in the settings tab.
Only teams with access to private repos can see that repo. So its a great way for groups to all contribute to a project because you can limit who sees what. As a teacher, if each student actually submits their own stuff (and not email around and have one person do it) you can actually see their commits down to the line they put in through the blame button.

About collaboration

Getting students to unlearn the code collaboration method they had been working with for years is a definite challenge. Putting in some best practices may be a good idea. Here is something I wrote up for the students in my research team to help them do this:

To ensure that we are not going to step all over each others code, these are the steps we will use when putting code into the repository:

All commits should be accompanied by an issue. If there is no issue for your commit, please make one first!

All commits should be put into a branch matching the issue number. Thus, if the problem the code is solving is described in issue 2, then the branch should be named issue2

before pushing your code to github make sure you merge in the most recent code on master to your branch and resolve any conflicts

push your code into the remote issue branch (if you want to work off your own fork then thats fine but issue branch on your fork)

submit a pull request for the code that you have submitted but DO NOT merge that code yourself.

assign someone else to review your pull request

if you are assigned a pull request, test out the pull request on your local machine BEFORE accepting it. Do not just click the button. If there are any problems, comment and let the submitter know and have them fix it. If all goes well accept the pull request to merge into master

There are other methods out there… but you probably will need to invest some time to teach whatever that method is.

About git and git clients

git is a revision control system and it is part of all linux distributions so if you are running linux, you already have git installed (unless it is a really really old linux release). For OSX git is installed as part of command line tools for xcode (if I remember correctly… on mavericks the first time I tried to type git at the command prompt, it installed those tools for me). For windows, you can download it from: http://git-scm.com/downloads

The above are command line tools for using git… and this is all you need for git and github.