All NSRC course materials (as well as workshop-kit build instructions and other resources) are held in git repositories. We use GitLab as a web front end to manage these repositories. If you do not have a login to the NSRC GitLab instance then please log a ticket with
firstname.lastname@example.org and one will be created for you
This document will walk you through the standard NSRC course development process within GitLab.
At a high level this consists of
Access the NSRC GitLab instance by going to the following URL
Once logged in, you should see your Dashboard with any repositories you have access to listed down the right hand side
You can see that some of these are listed under “NSRC Materials” while others are under particular usernames (such as “Dean Pemberton” or “Andy Linton”. the “NSRC Materials” are the stable versions of the repositories. If you wanted to teach a course, these are the ones you'd pull. Each of these has a Master of Curriculum role ensuring that at any point in time the are ready to be taught from. You shouldn't be taken by surprise with 'in flux' material by using one of these repos.
If we wanted to make some changes to a course. Then we use one of these stable repos at a base for the changes. The first step is to make a fork.
Click on the name of the repo that you want to develop for and you'll be taken to the project page.
From here click on the
Fork link in the upper right.
You'll be taken to a VERY SIMILAR looking page, but there are some important differences…
Notice that now rather than having “NSRC Materials” in the title (beside the fox icon) it has your username. This is because this version of the repo is a copy and it's been created under your namespace. You'll also notice that the URL has changed.
In the case of this example from:
a further hint that this is your copy rather than the stable “NSRC Materials” one.
Now that we have a fork of a stable repo to work with, how do we make our changes?
We need to clone this new repo to our local machine.
Regardless of the git tools you're using, the first step is to copy the repo URL from the repo project page. Be sure that you copy the SSH version rather than the HTTPS version. The text you're looking for is here.
If you're using the git command line tools, you would then issue a clone command like so.
$ git clone email@example.com:dean/openflow-sdn.git Cloning into 'openflow-sdn'... remote: Counting objects: 82, done. remote: Compressing objects: 100% (79/79), done. remote: Total 82 (delta 32), reused 0 (delta 0) Receiving objects: 100% (82/82), 17.82 MiB | 2.87 MiB/s, done. Resolving deltas: 100% (32/32), done. Checking connectivity... done. $ ls -l openflow-sdn/ total 22976 -rw-r--r-- 1 dean staff 796852 28 Sep 13:18 01-SDN-Introduction.pptx -rw-r--r-- 1 dean staff 610108 28 Sep 13:18 02-SDN-Openflow-Introduction.pptx -rw-r--r-- 1 dean staff 194173 28 Sep 13:18 03-SDN-Mininet.pptx -rw-r--r-- 1 dean staff 5577262 28 Sep 13:18 04-Openflow-Indepth.pptx -rw-r--r-- 1 dean staff 4536617 28 Sep 13:18 05-Openflow-UseCases.pptx drwxr-xr-x 18 dean staff 612 28 Sep 13:18 Archive -rw-r--r-- 1 dean staff 946 28 Sep 13:18 lab-setup.md -rw-r--r-- 1 dean staff 24395 28 Sep 13:18 mininet-openflow.md -rw-r--r-- 1 dean staff 9112 28 Sep 13:18 mininet-valve.md
This will result in a local version of your forked repo.
If you're using the SourceTree GUI:
This should then open a new repo window.
You should then work on whatever development you had in mind. Be this additions to the course, alterations, or deletions.
At each stage make sure that any edits and commits are done within YOUR fork.
To make a commit back to your version of the repo from the command line:
If you have created any new files which were not already in the repo you will need to use
git add to ensure these are added to any commit. eg
$ git add README.txt
If you're only made modifications or deletions then you can use the
-a flag to the
git commit command to handle these.
When you're ready to make the commit, issue the following command:
$ git commit -a -m "MY HANDS ARE TYPING WORDS" $ git push
This will commit any chances you've made back and push them back to your fork of the repo.
Make sure that any files you have changed (and want included in the commit) are staged. In the following screen shot you can see that I have a README.txt file which is unstaged.
Clicking the checkbox beside the file name will move it to the
Staged files area.
Once the files are staged, you can click Commit on the top button bar and type in a helpful commit message. Finally clicking Commit on the bottom right to make the commit
You can now see that a push is required, by the (1) on the Push icon in the tool bar.
Go ahead and push to make sure your central copy of this repo is up to date.
If all has gone well, we should be able to go back to GitLab and see that we have made a commit.
This is only on OUR fork of the repo however, not on the stable production version.
Because this is such an awesome change however, we want to make sure that it makes it back into the stable repo.
The way we do that is with a 'Pull Request'. Essentially we are going to the stable repo and making a request of the Master of Curriculum saying… 'Hey, I have a really good change in a repo over here. Could you please check it and include it in the stable version?'
This will open the Merge Requests screen.
This will show you all the differences between the branches and give you a chance to write a meaningful description for what the branch you are trying to merge is.
Also make sure that you assign this to the MC for the main production repo. You can find out who the MC for repo is by looking at this page: Curriculum Development Roles
If by some chance there isn't one listed, then don't just submit. Email
firstname.lastname@example.org and ask for an MC to be assigned.
At that point you can
Submit merge request
The Master of Curriculum will then be able to
Accept Merge Request after they have ensured (with the SME and EA, for the course) that there are no issues.
There is a discussion tab on the bottom of the merge request for the MC, SME and EA (see Curriculum Development Roles for an explanation of these roles) to enter comments as they proceed with their testing.
For a detailed description of the steps to be taken before pull requests are accepted into a stable repo, please see the guidelines in this page: NSRC Repo Merging Workflow
Once your merge request has been accepted, you can decide keep around your development version of the repo (a good idea if you are doing more work on this feature), or delete it and take another one next time you have something to develop.
That might seem like a whole bunch of steps involving different repos etc. This diagram may make things clearer (or it might not)
Finally here is some xkcd sourced inspiration for git commit messages