Category Archives: Seneca

I originally wrote this for the ACSE mailing list several years ago. This is an updated version of that post with some extra resources. It also looks at how I have been using git/github for my classes over the past few years.

Using git and github for your classes

git is the open source distributed revision control system created for managing the code needed for the Linux project. It lets you create a history of all the code of your project. 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 zip files. 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 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. You will also need to make 1 or more 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. All accounts and organizations are free to create. The difference between an organization account and an individual account is the type of controls you have to manage collaborators and repositories.

Under each account/organization are a number of repositories (repos). Each repository on github consists of a code repository (source code and its history), a wiki, an issue tracker, project organizer and graphical data related to the repository (analytics). Furthermore you can even use github to host client side webpages. Think of a repo as a place to put code and all things you want to see about that code in one place. It’s geared for people to work together on large code bases. Each repository can be either public or private. public means that the repository is fully accessible by anyone in the world. private means that the access is restricted.

You can use github for free without any extra work providing you are ok with the repositories being completely open (public). This means that all code, issues, wiki’s everything is open to the world. However, you may not want this for yourself or your student’s work. github charges for collaboration on private repos.

github makes money by essentially charging for privacy so under normal circumstances they would charge some amount for private repositories. You can see their pricing plans here: https://github.com/pricing

This is where github education comes in. You can request github for a discount if your personal or organization is used for academic purposes. Depending on the situation they may grant it for free (all my course organizations for example) or for a discount.

Typically they will want info about your school, number of students and so on. They will also want you to use your official school email on the account/org you are requesting a discount on. So make sure you make your account with that email.

Aside from you setting up an account, your students must each individually create a github account. The students can ask github for their own private repositories also through education.github.com but this is not necessary as the private repos can be created under your organization and you can simply grant access to your students. Creating private repos under your organizations means that you can maintain admin control over them. For example, we are suppose to keep eletronic work around for 1 year from end of course so having admin control means I determine when a repo is deleted.

Using Github for Hosting Course Material

I have found github to be a great place for me to host course material for my class. The way I do this is I create a repo for the course I’m teaching. Any example source code is simply added to the repo. Students can clone the repo to get the source code as it was intended (ie formatted like actual code) or they can view it online. github automatically syntax highlights all code in repo.

I use the wiki to set up links to course documents (addenda’s, assignments, links to resources, links to course notes etc. For larger documents (like course notes) I create links to them from the wiki (as a complete aside, I love gitbook.com for notes… write it once using markdown, get a web site /pdf/mobi and epub version of the notes).

For me, I opening up my course material to the world is not an issue so I typically keep this repository public but if you wish to restrict access, make the repository as private to your organization and grant only members of your organization access. You can also use the issue tracker as a discussion board for your students. If your students watch the repo they will get notified of changes to it. Here is a link to one of my course repos: https://github.com/seneca-btp500/btp500-f17

Accepting Student Work Through Github

Accepting work through github typically involves creating repositories for your students and granting appropriate access. You can then clone all their repositories to your computer once they have pushed up their work and go through their work on your local computer. NOTE: git generally does not deal well with binaries. Get your students to not push up any of their binary files (like .exe, .obj, .png etc.). binaries tend to bloat the repo and make it much slower to clone.

One change that github made over the years that you need to be very careful about is the default repository permission of the organization. It use to be that the default permission was none. At some time in the point in time, github changed it to Read. This means that every member can read every private repo in the organization. Thus if you provide a bunch of private repos to your students for their individual homework (ie each student has their own), those repos would end up being visible to every other student in the org. You can change this default permission to none in settings.

Github Classroom

github classroom is not something I’m familiar with. I used a very early version of it and it has likely changed by now. With it, you can create a repository and then send a link out to your students. When they click the link it sets up their repos automatically under your organization. This is probably the easiest way for you to create repos for your students. The claim is that you do not need to collect your student’s github ids… my problem (at least with the early version) was not so much as getting the ids but associating a github id with a student’s real name. However, perhaps an easy way to deal with this would be to have your student modify the readme so that their name is in it. I’ll try it out next term and update this post again.

Creating Repos/Teams for Your Students Manually

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 a particular 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.

For those of you who can run bash scripts I wrote some scripts that can automate the creation/cloning/deletion of repositories for an organization. You can gather info from your students with a google form then download the data as a csv file. Modify the script according to the comments. Then run them.

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 the revision control system that github is built on. To get the most out of github, it is a good idea to learn at least some basics of git.

As git was built for handling code for the linux project, 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 (type git in the terminal command prompt to see if its installed). 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 locally for git and github.

While a student, I learned a bit of assembly as part of degree. I never had a strong feeling about it. I wasn’t particularly interested in it as it just wasn’t something I thought I would do. I didn’t see the point of it. I know of its existence, knew what it meant. It gave me a sense of the different parts of how a computer works. I just never really thought I would ever want to write code in it. So I chalked it up to one of those courses I had to take and left it at that.

In the SPO600 course, we look at how code can behave when it hits the machine level. Two programs compiled on different processors will generate different assembly. I knew that when you write C code, the compilation happens in essentially 3 phases

preprocessor –> compilation –> linking

I knew that what came out of preprocessor was still basically C. What came out of compilation was an object file, and linking puts it all together.

I did not know how to look the object files though until now.

To stop the compilation after compilation phase you use the -c flag which brings you .o

For both the executable and the object file you can look at the assembly by using:

This semester I decided to audit my colleague Chris Tyler’s Software Portability and Optimization (SPO600) course at Seneca College. I think it is important to keep learning new things especially in our field that is ever changing. I remember how as a student and my profs would talk about punchcards (or how they luckily missed having to deal punch cards by one year). Now I think back to all the things that were true when I was a student that are so not true today (2MB of RAM was standard on a PC, significantly lower processing speed, no way to get viruses via emails cause its just text…). Things keep evolving and it is good to keep learning.

I decided to take this course in particular because Chris had told me about how compilers don’t actually translate the code we write into what we think . I thought it was fascinating how our model of what happens is so different from what actually happens once our code compiles. I wanted to find out more.

Another reason I wanted to do the course was because I also teach the data structures and algorithms course(dsa555 and btp500) and in that course we talk about algorithms and their implementation at a high level. We make broad generalizations like division is same speed as addition and we look at run time at an algorithmic level without any consideration of hardware. There, big-O runtime is king. SPO600 goes to the other end and looks at how optimization works when you get really really close to hardware. We even look at assembly code (last time I did assembly it was on 68000 ). I am finding the material fascinating and the next few posts that I write will be about things I’ve learned so far.

Once again, it is almost that time of the year for school to start once again. The summer has been an interesting one and this blog is a reflection on some of the things I did.

I had a good number of summer projects planned… but I only really got around to one of them. This summer, I wrote a guide to using p5.js with my cousin Ben, who teaches at an international school in Hong Kong. We wanted something that a teacher could use with their students in the classroom. We decided to write the guide using an online publisher named gitbook (I love gitbook for writing notes for my students. Write it once with markdown, get it published to web, pdf, epub and mobi… awesome)

I had actually started this project back in February. I got to about chapter 3 and I hated what I was doing with it. I felt that it was very wordy, too much reading, not enough getting to the fun programming parts. I remember learning to program when I was a kid. I didn’t want to read about how things were done. I didn’t care about the background of BASIC… I just wanted to write programs to make my computer do things.

After talking things through with Ben, we decided to take a different approach to our project. What is the minimum amount of background info/setup we need in order to get started? How can we allow someone to write code with as little setup as possible? It turns out that we only need to write about 3 paragraphs, include a picture guide, add a link to a video and use an amazing web based editor.

Sometimes, I teach introduction to programming and the first week typically involves explaining how to set up the development environment. It takes time to do this. How to get the compiler. How to get an IDE. how to claim your unix account. Where to find your text editor. The joys of pico/nano (don’t laugh too hard…it was the first editor I learned how to use on unix…)…vi, emacs, gcc, vs, xcode… its a lot of setup. I know a lot of us take this stuff for granted but think about what happens when you get a new computer… getting your dev environment set up is not a fast process. So, how do we simplify this as much as possible? How do we get to the fun parts as quickly as possible?

It starts by choosing tools that will minimize the setup. p5.js is a JavaScript library. To use it, you need to get the library files from p5js.org. You need to set up an html page and you need a JavaScript file to write the script in. After you set up your html page, you actually generally do not modify it. You only need to edit your js file so even though you absolutely need the html page its not actually part of the program you are writing. For tools you typically need a web browser and an editor. This is not a lot… but if you are first starting or if you are in an environment where what you are allowed to put on your machines is limited every extra thing you need to do before you start coding makes it that much harder to start.

To help simplify this setup, we decided to use Mozilla’s Thimble editor. It is an html/css/js online editor. It also allows you to publish your work. By doing this, we eliminate the text editor (and if you want to publish your work, we eliminated the webserver too). Using Thimble means that the only application we need is a modern web browser.

Furthermore, and this is the really cool part, using Thimble means that we can actually setup the basic p5.js project. Ben and I created an account on Thimble. We then set up thimble project with all the files need (the p5.js lib file, the html file and a stubbed out JavaScript file for people to write in). The JavaScript file contains some starter code for the p5.js sketch. Thimble also allows us to write our own tutorials. Thus, we can write instructions on what to do inside thimble. We then publish this project (one button inside thimble). We get the link off of the Remix button from the published page and put that link into our project book. Each chapter of our project book contains a goal (typically an image) to show what we are aiming for. This is immediately followed by a link to the related thimble project remix. The remix contains instructions (typically where to write the code, what to write). In otherwords, all you need to get started is to click a link! No other setup.

The guide then continues on with more detailed explanations for those who want to know the why for each of the topics covered. Towards the end of the guide, I added the chapters about how to setup your own sketch outside of thimble and some background material.

There is still a lot of work to be done on our guide for sure. Currently we have only one very basic project. We will add more in the future but I’m pretty happy with what we have done so far. You can access our guide here

On a more personal note, I started the summer by helping my parents out for a bit at their restaurant. Its very different from my usual job to say the least. My part of the work was not really hard but the hours are quite long. All I can say is how much I respect my parents for doing it. I know how hard they have worked all these years to raise my brother and I. I am forever grateful.
I am also continuing to decorate my new place. This summer’s decorating involved the balconies, one of the best features of my new place. I grew some strawberries, some herbs, and some cherry tomatoes (why are the leaves drying out ? there is plenty of water. help!). I even put in a couple of chairs.

I also made a few pieces of pottery this summer mostly for myself. One of them is this garlic jar. I am rather happy with it.

For those unfamiliar, CDOT is an applied research group within Seneca College. Over the years we have worked on many different projects related to open technology in various areas. I am one of the faculty members involved with CDOT. Projects tend to run over the course of a semester or two. Students are hired either while they are studying or just after they graduate.

My team worked on projects related to 3D web graphics. This summer I had two projects. The first was a project with Box, to implement a 3D data visualization tool. The second was with a Gorilla Productions. The project was to implement realistic cameras for three.js. (cameras that behave as real world cameras do). In total I had 4 awesome research assistants working for me (Andrii, Barbara, Dmitry and Koji). They have done a fantastic job on their projects.

However, aside from my two projects, CDOT also hosted many other projects. One of the reasons the reasons that CDOT exists is to provide experiential learning opportunities to our students. A chance for them to work on real projects and develop skills. One of those skills is the ability to talk about their work. Thus, each Thursday was we have “Demos”. During that time, the teams will talk about their project and what they have been working on, problems they encountered, solutions they found. Yesterday, was the last day and everyone had a chance to talk about thoughts of on their summer’s work.

Generally the comments were all very positive. However, there did seem to be a few themes that were shared by multiple students. These were:

Being surrounded by other very smart people working on interesting projects has helped them develop as programmers

Demo days helped them learn from other teams even when they were not working on remotely the same thing.

Demo days made them less nervous about speaking in front of crowds

CDOT provided opportunities to work on something important with a great amount of freedom to design and implement their work

CDOT experience has helped them to either find a job (a couple of students will start in new positions right after labour day) or the confidence that they will be able to find one shortly.

I truly believe that CDOT is one of those places that are unique and special. We have students that do very interesting work on a wide variety of projects. Our students are very bright, and I have always admired their ability to exceed my expectation. Many of you have taught me things I did not know. To all the RA’s at CDOT, know that you are the ones that make CDOT special. When I see what you do, when I see what you have accomplished, I am reminded of why I teach. Thank you!

There are two major problems that I see when I look at my student’s documentation for their code.

no documentation … we are talking about not even having a header with their name on it here for assignments

too much documentation – repeat all code in comments!

Both of these are problems. One may not seem like a problem but it in fact is.

The lack of documentation in its entirety is just a job of incompleteness. Most students understand that when they don’t do it, they will lose marks. They know they should but for whatever reason they didn’t. Its like knowing you should exercise but you don’t…This post isn’t about that. The complete lack of documentation is relatively simple to address.

This post is addressed to those that document everything. I know students who do this are very proud of their work and they put a lot of effort in it. I get that. I’m not knocking that. However, I would like to ask you to please please please please please stop doing it. Don’t do it. It isn’t better. A bad comment is worse than no comments at all.

Here are a few commenting guidelines:

please don’t repeat your code in your comments… your code is there… anyone reading it sees what it does if they need to know it. “this is a for loop” is not useful. “this loop runs 10 times” completely silly. “assign 5 to x”….please stop. please stop.

I have found that comments become sacred over time. programmers do not hesitate to alter code… and yet comments…well you can’t touch those (sarcasm). So, with this in mind, I encourage you to write as little comments in the body of your code as possible! Your code should be clear enough to read. Unless you are doing something very very tricky, don’t put in a comment in the body of the code.

Comments that are useful explain reasoning, that may not be immediately obviously. In my first programming job I was trying to hunt down a bug in a program and I saw this comment “find first sunday in april and last sunday in october”… I could tell thats what the code was doing… that wasn’t hard. I then spent a day trying to figure out why they needed to do this and whether or not it was the cause of the bug. What they did and how they did it was clear… the code said as much. I couldn’t figure out why it was that this was something that needed doing. Finally, I realized the why and changed the comment to “adjust time calculations for daylight savings times”… to me this makes way more sense. I’m not saying how to do it (and the how has changed since then as the time of year that daylight savings time comes into effect has changed).

Here is are the three things you should document:

Have a header! State who wrote the code, major modification dates, versions etc

state the intention of each function (not how but what it is suppose to do), its parameters, expected return value and restrictions.

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.