ICS-E4020: GitHub workflow

GitHub workflow

We will use the Git version control system and GitHub to return exercises.

You will first need to set up your personal Git repository, see below for more information. In what follows, we will assume that you are on a Maari-A computer (physically or remotely), you have already set up your personal Git repository, and you are in the root directory of your repository.

Brief overview

Your submission each week is whatever is there in your personal Git repository on GitHub, at the end of the week. The basic workflow is as follows:

Repository layout

In the root directory of your personal repository, there is a file README.md with more information on the technical details. There is one subdirectory per task. For example, everything related to task MF1 is in subdirectory mf1. You will put your code there, and you will also receive feedback there.

Grading tool

There should be a symbolic link grading available both in the root directory of your repository, as well as in each subdirectory. You should be able to run the following command anywhere:

    ./grading

If you run it without parameters, it will give brief usage instructions. Try, for example, the following commands:

    ./grading info mf1
    ./grading overview all
    ./grading show all

In particular, the command ./grading info is important as it will explain precisely how each task is graded.

The grading tool does everything locally, in your local working copy of your personal Git repository. Hence it is always safe to use — you can just run it and see what happens. But this also means that just running it is not enough: you will also need to commit and push everything that you want to submit to your personal Git repository on GitHub.

Developing your solution

To solve task MF1, you switch to directory mf1 and start programming. In this case, you are supposed to edit the file mf.cc; everything else is already there. Once you have implemented it, you can compile it with:

    make -j

If it compiles fine, you can run some simple tests with:

    make test

You can also run some benchmarks to get a better idea of the performance:

    make benchmark

But of course you can always develop your own unit tests, your own benchmark tools, etc. You are also encouraged to try out e.g. the program pngmf to actually do some median filtering for you own PNG files. If something goes wrong, isolate the problem, find out precisely which test fails, start debugging it in isolation, etc. See the README.md file for help with e.g. debug builds.

Submitting your solution

Once you are happy with your code and its performance, you can try to submit it for grading. You can simply run the following command in directory mf1:

    ./grading do

It will run a bunch of tests, do some benchmarking, and, if all goes well, it will create the file

    submission-WEEK.txt

where WEEK is the current week number (1–6). The submission file contains the running time of your code, and this determines your preliminary score. Use ./grading show to see your current points and ./grading info to see the point thresholds for each week.

You can safely run the grading tool any number of times, for any number of tasks, during any course week. If you have already got a submission file for the same week, it will be automatically updated if your latest performance is better.

Once you are happy, add all relevant files to your personal Git repository, commit, and push. For example:

    git add mf.cc submission-1.txt
    git commit
    git push

Please note that you must commit and push both your solution (e.g., mf.cc for task MF1) and the submission file (e.g., submission-1.txt for the first week) to your Git repository on GitHub. If you are new to Git, or just feel a bit unsure, go to https://github.com with your web browser and see that you really see both of the files there.

Also please note that you must do all this before the weekly deadline. It does not matter when you run the grading script. What matters is when you successfully push everything to GitHub.

Receiving feedback

After each week, the teaching assistants will review your submission, grade it, and give feedback.

Let us assume that you have submitted the following files during week 1:

    mf1/mf.cc
    mf1/submission-1.txt

Your teaching assistant will study your code and then create the following file in your repository:

    mf1/feedback-1.txt

The file will start with an adjustment to your score. Usually, it is simply 0, meaning that everything is fine, and your preliminary score is also your final score. If needed, there may be negative adjustments (e.g., your submission seems to run fast but it violates some rules) or a positive adjustment (e.g., personal deadline extensions in the case of illness). But all of these will be hopefully rare.

After that, there will be greetings from your teaching assistant: for example, explanations of the grading, and feedback on your implementation. Read it!

You will receive feedback files by simply pulling the latest changes from GitHub:

    git pull

Once you have feedback there, you can also use the grading tool to see your final scores, for example:

    ./grading show mf1
    ./grading show all

Submitting your solution: open-ended tasks

Some tasks (e.g. CP5) are open-ended task. No automatic grading is done. You will submit your solution for grading by running the following command in the right directory:

    ./grading submit

It will just do some sanity-checking, verifying that you have at least the report in the right directory, and it will then create the file:

    submission-WEEK.txt

The contents of the submission file are not important here, it just serves as an indicator that your submission is ready for grading. As usual, add, commit, and push this file to Github.

Receiving feedback: open-ended tasks

For open-ended tasks, the preliminary score is always 0. The final score comes from the feedback file.

Resubmissions, late submissions, etc.

Before the end of the lecture week 6, you can always resubmit any of your previous solutions. Just fix your code, run ./grading do again, and commit and push everything to GitHub.

Resubmissions are always safe. You will get a new score each time you resubmit, and your final score for each task is the maximum of the scores from all weeks.

Just note that for many tasks, you will get the highest points if you solve it early. Lower points apply to both resubmissions and late submission.

The course stops after the lecture week 6. No submissions of any kind are accepted after that.

Summary

You will implement mf1/mf.cc. You will commit and push it to your Git repository.

The grading tool creates mf1/submission-1.txt. You will commit and push it to your Git repository.

The teaching assistant creates mf1/feedback-1.txt. You will pull it and read it.

Now the grading tool can show your final score for week 1, for task MF1.

Setting up Git repositories

In brief, we will set up your Git working copy so that its origin points to your personal repository on GitHub, and upstream points to a common read-only repository with the code templates. A little bit of extra effort is needed, as your repository is initially empty — to initialise it with the code templates, we will need to first pull from upstream and then push to origin. This is a one-time setup only.

Step 1: Creating an account on GitHub

  1. Setup a GitHub account if you already do not have one: https://github.com.
  2. Complete the prerequisite test.

Step 2: Join the course organization

  1. Eventually, you should receive an invitation by email to join the course organization from GitHub. Accept the invitation.
  2. Once you have accepted the invitation, go to https://github.com/ICS-E4020-2016 and verify that you see the two repositories exercises and solutions-YOUR-ACCOUNT listed on the page.

Step 3: Initialise your git repository

Note: You can also use GitHub via ssh if you create ssh keys. In the following, simply replace everything starting with https://github.com/ICS-E4020-2016/ with git@github.com:ICS-E4020-2016/.

On your computer, run the following commands:

    $ git clone https://github.com/ICS-E4020-2016/exercises.git
    $ cd exercises

We now setup git to use two remotes as follows:

    $ git remote rename origin upstream
    $ git remote add origin https://github.com/ICS-E4020-2016/solutions-YOUR-ACCOUNT.git
    $ git push -u origin master

Now the remote upstream should point to the read-only exercises repository and the remote origin points to your own private repository. During the course, you pull all exercise related material from upstream but submit your own solutions to origin.

After completing the above, check that

    $ git remote -v 

outputs the following:

    origin  https://github.com/ICS-E4020-2016/solutions-YOUR-ACCOUNT.git (fetch)
    origin  https://github.com/ICS-E4020-2016/solutions-YOUR-ACCOUNT.git (push)
    upstream    https://github.com/ICS-E4020-2016/exercises.git (fetch)
    upstream    https://github.com/ICS-E4020-2016/exercises.git (push)

Also go to https://github.com/ICS-E4020-2016 with a web browser, find the repository solutions-YOUR-ACCOUNT there, and make sure you can see everything there as well (a full repository with all code templates).

Now you are ready to use Git as usual. Run git add and git commit to commit any changes you have made, and then use git push to push your changes to GitHub. Run git pull to receive the latest changes from GitHub. See above for more details on the workflow during the course.

Retrieving new templates (if needed)

Occasionally, we may e.g. fix bugs in the code templates, Makefiles, grading tools, etc. To make sure that you have the latest changes, pull from upstream:

    $ git pull upstream master

Multiple clones (if needed)

After you have set up your Git repository on one machine, it is easy to create clones on other machines, too. To clone it, simply run:

    $ git clone https://github.com/ICS-E4020-2016/solutions-YOUR-ACCOUNT.git exercises
    $ cd exercises

You may then also want to set upstream properly here, too, so that you can pull from upstream if needed:

    $ git remote add upstream https://github.com/ICS-E4020-2016/exercises.git

Using ssh with GitHub (if needed)

Typing in your username and password gets old rather quickly. To remedy this, you can generate ssh keys and use them with GitHub:

  1. See the GitHub instructions on generating ssh keys.
  2. Configure your course git repositories to use ssh connections:
        $ git remote rm upstream
        $ git remote add upstream git@github.com:ICS-E4020-2016/exercises.git
        $ git remote rm origin
        $ git remote add origin git@github.com:ICS-E4020-2016/solutions-YOUR-ACCOUNT.git
    

Now git pull or git push should not ask you your password each time.

Tips

Never used Git before?

Read the Git tutorial first.

Browse your repository on https://github.com with a web browser to familiarise yourself with the system. The front page of the course organization is https://github.com/ICS-E4020-2016 and you should find your personal repository there. If you think you have pushed something to GitHub, double-check it online.