Gitlab tutorial

This short tutorial helps you to:

1. get a general idea of Git
2. get a general idea of Gitlab
3. get a general idea of how course project(s) are submitted

Git

Git is a popular version control system to help you control the software versions and work with others from all over the world. If you are familiar with Git, please skip this section.

Imagine the timeline of a software lifecycle: it can be linear (you keep adding components and features into it to fulfill an ultimate goal); it can be a tree (maybe you are not sure about the implementation at some points and you decide to try both ways); or it can be a graph (you find out that two solutions can be combined to achieve the goal better). The above are just the situations where you are the only maintainer of a software project. Git is also good at collaborative work, which is not covered in this tutorial.

After the logical models, it's time to get familiar with the most frequent git commands.

When you want to initialize a new empty project under git, init is the command you should use.

mkdir -p project_path
cd project_path
git init

If you want to commit a version, first you should logically mark the files that should be taken care of by Git.

vim test.py # do some editing and save
git add test.py

And you should commit to really save current tracked files as a single version.

git commit -m "This sentence is a mandatory comment to help remember the improvements introduced into this version over the last version"

Git is purely distributed, which means the "life graphs" of a single software may be different at different repositories. For example, you have a desktop at your school lab, a laptop at home, and you have a public repository on a gitlab server (you will learn how to put your codes on our gitlab server later in this tutorial). You may choose the gitlab server as a central storage of your codes and synchronize the versions between the desktop and the laptop.

The first thing you should do is to create the project from the server web interface (covered later) and you will get both an HTTP and an ssh locator to your project say https://domain/path/to/repository. Then you should initialize your project using command "clone" on both your desktop and your laptop.

cd to/the/path/you/wish/to/put/the/project/in
git clone https://domain/path/to/repository

Or if you have initialized a repository locally on your laptop, you should register the newly created repository at the server as a remote repo, which we usually name it "origin".

git remote add origin https://domain/path/to/repository

And then you can push your current committed versions to the server or pull the versions from server to your laptop or desktop. Here is an example. When you come to your lab, you may want to develop on the latest version on the server, so you do a pull. When you want to go home, you do a commit to mark a version locally and you do a push to synchronize the versions to the server. So when you come home, the latest version is on the server, you can pull it to your laptop and continue working on it.

# start working on your desktop
git pull "origin"
# finish working on your desktop
git commit -m "today's update"
git push "origin"
# start working on your laptop
git pull "origin"
# don't forget to commit and push to synchronize with the server

You may find out that this synchronization approach is very inefficient given that you have Dropbox or some other synchronization tool. Yes, the above example is just to help you understand how the synchronization is performed. You can imagine two different developers working on your laptop and your desktop, then you have had the first glance at the Git world.

This tutorial is very short and some more interesting features and details are found below:

Git book (Comprehensive)

Interactive tutorial

Git installation

Git GUI client on all platforms

Please do NOT cover Github sections in all the above links because we will use Gitlab instead.

Gitlab

Gitlab is a server-side software to work as central storage for software repositories. It is very similar to other tools, e.g. Github, Bitbucket, etc. While the core of them is the server side Git, just to answer requests for pull and push, etc., many other features are built around the core Git functions to help the development workflow more smooth and more controlled. The additional features we are going to use in this course are:

1. A continuous integration (CI) script default to Python and may be edited by your self to help test your code on a clean docker container.
2. A server-side hook to automatically grade your submission based on unit tests.
3. A server-side hook to limit your storage usage within a reasonable bound (I believe you cannot reach the limit if you are doing correctly).

Some may argue the hooks are core functions provided by Git itself, yes, but the Gitlab enables me to deploy a self-managed Gitlab server and add these hooks, and you can see the error information on the server website if you submit on the website.

The general view of a project is as follows:

#1 is the URL to your repository. #2 is the interface where you can add files, edit files, and make a new commit just on the server, without using Git commands on your machine. #3 is the indicator of the CI successfulness of your last submission. And you can read the build and test log if you click the icon.

Submit your project

As we plan to automatically grade your code and give you feedbacks about problems in your code at the first place, you are required to register an account on our Gitlab website using your own UCSC email registered on canvas. 

Note that your accounts on our Gitlab website have nothing to do with the accounts on Gitlab.com

As it runs on a desktop in our lab, it may not be always available. Please wait a while or just inform me about the inaccessibility.

After the registration using your UCSC email, you should be able to see an empty project under group cmpe252A.fall18 and the project name is the same as your email account. If not, it may be just because it is too early.

You can use any language to fulfill the tasks in the course project. You may need to explain your code in detail to me if you choose languages other than: Java, Scala, Kotlin, Python3, C, C++, C#, Go, Julia, Matlab, Mathematica, VB, as well as JavaScript and its derivatives.

After pushing versions from your local machine to the server, the server will check the validity of the latest version following the instructions in your .gitlab-ci.yml script.

The default .gitlab-ci.yml file is for Python3. You may need to modify it if you are using other languages. The grammar is super easy and you can get some hints when you add files via the interface #3 like the following:

Please note that the CI system is to help you define your own build and test workflow on a clean machine and have a better understanding of your grade from the log. You are NOT required to fulfill that feature as we are grading via our script conventions.

As there are two course projects, we may have different conventions for our automatic grading purposes. We will let you know the conventions later. And empty projects cannot passing the unit tests but are complete in the conventions will be provided as references for both projects. The automatic grading may not be implemented for some reasons, and we will also let you know if you have to submit your code directly to us.

The last but not the least, the grades automatically issued is the upper bound. Situations undermining your grade include but are not restricted to:

1. Plagiarism
2. Test-passing oriented programming, which means the code passes some tests, but it is done intentionally for the specific input and is not generalized at all. 

That's all about our Gitlab tutorial. After all the Gitlab is a tool for project submission. Should something happen, we would fall back to face-to-face submission. Hope you do well! 

Update: we will fall back to face-to-face submission because automatically grading for all languages is very hard to implement. You commit and push your code to the project before the deadline, and then come to TA and show that your code is working well. You will be asked to pull your code from the Gitlab first if the demonstration is after the deadline.