User Tools

Site Tools


2015:repo-documentation:gitlab-workflow

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

2015:repo-documentation:gitlab-workflow [2016/02/03 05:04] (current)
Line 1: Line 1:
 +====== NSRC GitLab Workflow 101 ======
  
 +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 ''​tasks@rt.nsrc.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 
 +
 +  - Making a fork of the relevant repository
 +  - Cloning that fork to your local machine
 +  - Making changes to the local repo
 +  - Committing them back to the development fork
 +  - Creating a 'Pull Request'​ so that the upstream MC can determine if your changes will be incorporated into the main repo.
 +
 +
 +===== Making a fork of the relevant repository =====
 +
 +Access the NSRC GitLab instance by going to the following URL
 +
 +   ​https://​git.nsrc.org/​
 +
 +
 +Once logged in, you should see your Dashboard with any repositories you have access to listed down the right hand side 
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.02.00.png?​300 |}}
 +
 +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.
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.04.03.png?​600 |}}
 +
 +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...
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.05.51.png?​600 |}}
 +
 +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:
 +
 +   ​https://​git.nsrc.org/​nsrc/​openflow-sdn
 +
 +to
 +
 +   ​https://​git.nsrc.org/​dean/​openflow-sdn
 +
 +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?
 +
 +
 +===== Cloning that fork to your local machine =====
 +
 +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.
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.10.15.png |}}
 +
 +If you're using the git command line tools, you would then issue a clone command like so.
 +
 +  $ git clone git@git.nsrc.org:​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:
 +  - Click File -> New/Clone -> Clone from URL
 +  - Enter in the repo URL and give the repo a valid destination path ** NOTE THAT THIS SHOULD BE DIFFERENT TO WHERE EVER YOU ARE STORING THE STABLE PRODUCTION REPO **
 +  - You can also give it a more unique name so that it's easier to spot that you're in your development fork.
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.15.45.png |}}
 +
 +This should then open a new repo window.
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.17.16.png?​600 |}}
 +
 +
 +===== Making changes to the local repo =====
 +
 +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.
 + 
 +===== Committing them back to the development 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.
 +
 +
 +In SourceTree:
 +
 +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.
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.31.20.png?​600 |}}
 +
 +Clicking the checkbox beside the file name will move it to the ''​Staged files''​ area.
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.31.58.png?​600 |}}
 +
 +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. 
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.35.58.png?​600 |}}
 +
 + Go ahead and push to make sure your central copy of this repo is up to date.
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.36.57.png?​600 |}}
 +
 +
 +If all has gone well, we should be able to go back to GitLab and see that we have made a commit.
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.40.36.png |}}
 +
 +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.
 +
 +===== Creating a 'Pull Request'​ =====
 +
 +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?'​
 +
 +On **YOUR** fork of the repo (ie https://​git.nsrc.org/​dean/​openflow-sdn not https://​git.nsrc.org/​nsrc/​openflow-sdn) click on the ''​Merge''​ tab.
 +
 +This will open the Merge Requests screen.
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.45.46.png |}}
 +
 +From here you want to create a ''​+ New Merge Request''​.  ​
 +Select the branches that you would like to merge on the next screen (probably both ''​master''​) and click ''​Compare branches''​
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.48.15.png?​600 |}}
 +
 +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:
 +[[2015:​repo-documentation:​curriculum-roles|Curriculum Development Roles]]
 +
 +If by some chance there isn't one listed, then don't just submit. ​ Email ''​tasks@rt.nsrc.org''​ and ask for an MC to be assigned.
 +
 +At that point you can ''​Submit merge request''​
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.51.26.png?​600 |}}
 +
 +
 +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 [[2015:​repo-documentation:​curriculum-roles|Curriculum Development Roles]] for an explanation of these roles) to enter comments as they proceed with their testing.  ​
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.51.26.png?​600 |}}
 +
 +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: [[2015:​repo-documentation:​merging-workflow|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)  =)
 +
 +{{ :​2015:​repo-documentation:​gitlabworkflow.png |}}
 +
 +Finally here is some [[https://​xkcd.com/​1296/​|xkcd]] sourced inspiration for git commit messages =)
 +
 +{{ :​2015:​repo-documentation:​screenshot_2015-09-28_13.31.35.png | [[https://​xkcd.com/​1296/​|GIT Commit]] }}
2015/repo-documentation/gitlab-workflow.txt ยท Last modified: 2016/02/03 05:04 (external edit)