Lab #9: Git branches and more of GitLab

For this lab, do not change order of the exercises when working on them - some of things would stop making sense and you would not see the effects we want you to see.

Fork the repository teaching/nswi177/2020-summer/upstream/examples to your own namespace.

Clone your fork of the teaching/nswi177/2020-summer/upstream/examples repository to your machine.

For this lab, we will be using the csv_calc directory.

Look at the csv_calc.sh script and run it as described in the read-me file. Also read how the script works (that is in the read-me too).

Notice that the script prints error message when the expression is invalid. For example, for ./csv_calc.sh 'sum=t01+' <example.csv. However, exit code is always 0, denoting success. Hint.

The allways-good error code is a bad practice that should be fixed. But it is not the only thing that needs fixing. To keep track of the unresolved issues of our project, let’s record them permanently. Open the homepage of your fork in the browser. In the sidebar, you should see a link to Issues: following the link would tell you that The Issue Tracker is the place to add things that need to be improved or solved in a project. That is exactly what we need ;-).

Let’s create a new issue describing the problem.

Fill-in the title - think about it as a e-mail subject - it has to summarize what is wrong. Write also a description - in this case you might be thinking that title Bad exit code has it all. It does not! Write an example of bad behaviour there. Note the Markdown link there that brings you help for Markdown formatting - knowing about ` and ``` is a must for every programmer :-).

For further reading, look up the query on how to write good bug report in your favourite search engine and read at least one article about it. It is worth it.

The bad exit code is not the only issue of the code. Let’s create an empty file precious.txt in our directory and run ./csv_calc.sh 'sum=t01 )); rm -f precious.txt; : $(( 0 + 2' <example.csv.

The file is gone because we have injected malicious code into the expression.

This example of a security breach probably made you smile. But issues like this are real enough to not forget about them.

Thus, create another issue for this in your project.

Again: use a descriptive title, provide a meaningful description. Really. Use this as a practice for the team task.

View a list of your issues. Each issue should now have a number next to it that we can reference later on.

Since you have read the article from the Before class, you know that you should never commit directly to master branch. Especially when working on a new issue or when fixing a bug. We will follow this rule (with a few well-meant exceptions) through the rest of the labs.

We will start by fixing the bug with exit code. Let’s create a branch for that and switch to that branch.

In bigger team, there are even rules for proper branch naming. For this exercise, we will use issues/N for branches that are supposed to fix an issue with number N.

Now, create the branch and switch to it.

Hint.

Right now, the switch has no visible effect - both master and issues/1 branches refer to the same state of files.

Write a fix for the issue.

Hint.

Commit the change. We will now use a cool GitLab feature where you can reference a particular issue from within a commit. Such commits are then listed together with issue details. It is only needed to prepend hash in front of the issue number.

As our commit fixed the issue, we will also add a special keyword fixes to the commit message to automatically close the issue (there are plenty of issue closing patterns).

Note that it serves too purposes - it saves time and it provides a valuable reference to which commit was actually responsible for fixing the bug.

Hint.

You should not have any uncomitted changes in your project. Let’s switch back to master branch. Check that the script does not contain your fix.

Note that if you have your script opened in a text editor, it should warn you about file being changed on disk. If not, reload the file manually.

Hint.

Switch back to issues/1 branch and push it to GitLab. If you run git push (as you were used to), Git will complain that the current branch has no upstream branch. It means (more or less) that you are pushing this branch for the first time and Git wants to make sure how to name the branch at the server.

Nice thing is that Git offers you the command to run to ensure the branch is pushed.

For now, ignore the link that GitLab sent you back.

Hint.

Open your project in the browser again. Check that your issue now contains a link to the commit that mentioned it and on the homepage of the project, you can select which branch to display.

Let’s now fix the second issue (the code-injection one). Create a new branch, resolve the issue and commit the fix.

Do not push the branch yet.

Some questions and thoughts:

• Why do you need to switch to master first? How would the branching look like if you branch from issues/1? Why is that bad?
• To actually fix the issue, consider using printf command that works similarly to printf you may know from other languages (or to .format from Python). %q directive is the one you are looking for.
• Do not forget to include closes #2 (or similar) in the commit message.

Hint.

Let’s assume that you just now noticed the typo in README.md. (Hint: form is not from.)

We want to fix that right away and we will do it (just this one time) directly in master branch.

So, switch to master branch (you already committed the fix to issue #2, right?), fix the typo and commit it.

Push your changes from master branch.

Open the Repository -> Graph page in your browser (from your project). It should show you your branches graphically.

Switch to branch for the second issue and push it to GitLab too. You will need to use the --set-upstream switch again.

Notice that after the push, you ought to see a text informing you about opening a merge request with a link.

Open that link now in your browser.

Merge-request is an advanced feature of GitLab that targets big teams. In big teams, code review is required before any code can be pushed to the master branch. We will now use it as a way to merge our fix in GitLab.

You will notice that the merge request is not yet submitted. Title and description are pre-filled and they look similar to the form we have seen with issues. Actually, they are very similar: issues describe known problems (or feature requests), merge requests describe how the problem was fixed.

It is a good practice to mention which issue the merge request closes (or issues that are related).

Again, Markdown formatting can be used.

Create the merge request now. WARNING: Double-check the destination of the merge request. It has to be branch in your repository, not the repository you forked from.

In big teams, other developers would now comment on your code and also automated checks would be run (you will setup automated checks on some of the next labs).

For personal repositories, merge request still make sense: they allow the developer to quickly check that everything is okay (i.e. that all files were actually committed etc.).

Let’s merge the request now (there is a big button for that).

Keep the default and do a merge (i.e. not a rebase or a squash).

The merge request being closed, we should see a new commit in the master branch.

You may also look at the repository graph again to see how the commits look after the merge.

Check issues of your project now.

Back in your local clone of the repository: do not forget to pull the latest changes from master (GitLab created the commit on the server only). Hint.

We will now merge the first issue directly on command-line without opening a merge request.

First, we need to ensure that we are on the branch we want to merge into. Usually, that would be the master branch.

Next, let’s do the actual merge. It is as simple as

git merge issues/1

And it is done. Push the master branch again and check the repository graph now.

Check issues of your project again.

Try to re-do the above steps for another two issues.

1. The script should be more user-friendly when it is incorrectly invoked. E.g. when user runs it without any arguments or when it is executed with --help.
2. What happens if you re-create precious.txt (it was empty) and append the following line to the input CSV Mayor Humdinger,0,0,0';rm -f precious.txt;:' and run again the command from README.md?

Open a new issue for each of the above and create separate branches for them. Merge one of the branches via a merge-request, second merge from the command-line.