Version Control - Fab Academy 2021 Recitations

.logo[
	![Fab Academy 2021 logo](https://gitlab.fabcloud.org/academany/academany-mkt/-/raw/f6a6d3114b18a0f88ee700b29c9819e41322474a/FabAcademy2021/Logos/F_r-logo.png)
]

### Recitation

_February 1st, 2021_

# Version control and Project management

**Julian Gallimore**

.logo_tiny[
	![Fab Academy log](https://gitlab.fabcloud.org/academany/academany-mkt/-/raw/f6a6d3114b18a0f88ee700b29c9819e41322474a/FabAcademy2021/Logos/F_Fab_Academy_Logo.png)
]

---

# Agenda

1. [Fab Cloud platform](#chapter-fabcloud)

1. [What is Git](#chapter-git)

1. [Setup your local environment](#chapter-git-setup)

1. [Git pushing changes](#chapter-git-push)

1. [GitLab CI](#chapter-gitlab-ci)

---

name: chapter-fabcloud
class: center, middle
background-image: url(images/versioncontrol.png)

# FABCLOUD

---
layout: true

**Fab Cloud platform**

---

## What is GitLab

GitLab is a web-based tool that provides a Git-repository manager providing wiki, issue-tracking and continuous integration and deployment pipeline features, using an open-source license, developed by GitLab Inc.

> https://about.gitlab.com/

---

## What is FabCloud

Our self-hosted version of GitLab, were we host all projects related to the academies and host student documentation websits. User login is managed by our Single-Sign-On service [fablabs.io](http://fablabs.io) (You should have an email with details how to login).

> https://gitlab.fabcloud.org/

.logo_small.center[
	![Fabcloud Gitlab login screenshot](images/gitlab-login.png)
]

---

## Fablabs.io

- Online platform that maps the FabLab network world-wide
- Provides the user account logins for our tools GitLab & Nueval

---

## Gitlab & FabAcademy sturcutre

We use GitLab for all the content related to Fab Academy.

#### What we do with Gitlab

1. Keep all student files under version control
1. Track [groups](https://gitlab.fabcloud.org/academany/fabacademy/2021/) of students, labs, instructors and staff
1. Host the FabAcademy class [site](http://fabacademy.org/2021) for (schedule, labs, students list pages)
1. Publish documents in the [Docs](https://gitlab.fabcloud.org/academany/fabacademy/2021/docs) group
1. Discuss class [issues](https://gitlab.fabcloud.org/academany/fabacademy/2021/class/-/issues)
1. Use Gitlab as a project management tool
1. Take meeting notes using [Markdown](https://docs.gitlab.com/ee/user/markdown.html).
1. Host personal documentation with GitLab Pages and using [static site generators](http://www.staticgen.com)

---

### Fab Academy GitLab structure

.logo_medium.center[
	![Fabacademy Gitlab repo organsiation](images/gitlab-groups.png)
]

---

**Git**

---
name: chapter-git

# What is Git

> [git-scm.com](https://git-scm.com)

Git is a tool used for tracking to your project files
Saving your changes is called a Commit
Everything is stored in a Repository
You can view all the commits in a repository to see who/what/when changes were made
If anything breaks, look back at your commits and undo what you did
You can also have a Git repository on your computer
After any changes to files you can push your commits to the cloud (GitLab)
The repository in GitLab is called the remote origin (this of it as the master version)

[Learn Git by Atlassian](https://www.atlassian.com/git/tutorials/what-is-version-control)

---

**ACCOUNT SETUP**

---
name: chapter-git-setup

## SSH Keys

Git uses the SSH protocol to establish secure communication between your computer and the GIT server hosting your repository.
This makes sure only you can update your repository and nobody else can tamper the communication.

**Without SSH Key you can only use the web interface**.

SSH Keys allow you to use the GIT repository securely, without requiring a password every time.

#### Generate your [SSH Key](https://docs.gitlab.com/ce/ssh/README.html#generating-a-new-ssh-key-pair)

- Linux and MacOS

```terminal
  ssh-keygen -t rsa -b 4096 -C "your.email@example.com"
  ```

- Windows
  [Using PuttyGEN](https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen)

---

### Add the public key to your GitLab profile

---

## Clone your project locally

Go to your students project page, in GitLab, and look for the blue "clone" button to copy the SSH URL.
Then in your terminal, enter the command `git clone` followed by the copied URL.

```terminal
git clone <paste-ssh-url-to-git-repo-here>
```

---

## Setup Git locally

It is a good idea to configure git on your computer with your name and email,
so that when you make commits they can be attributed to you.

```terminal
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

.caption[
	Please use the same name and email address as you use to login to GitLab (check your GitLab settings).
	Also if you have multiple Git accounts, you can run the commands with out `--global`, to set it only for your student repo.
]

See commit author below, from `git log`:
.logo_medium.center[
	![](images/git-commit-log.png)
]

---
name: chapter-git-push

## How to push local changes

After making some changes to files, you will want to push these changes to GitLab so they can get published.

First have a look at the state of your working directory and staging area.
```terminal
git status
```
Next selected the changed files, moving them to the staging area.
```terminal
git add docs/path-to-your-file.md
```
Commit the selected changes in the staging area, including a message.
```terminal
git commit -m "Added my name"
```
Push your new commit to remote repository, GitLab.
```terminal
git push
```

---

## About Git staging process

The diagram below illustrates the different areas in your local git repository.
.full-width[
	![](images/git-staging.png)
]

---

## How to pull latest changes

It is a good idea to always check if there are commits on the remote repository you do not have locally.
This can happen if you made changes directly on GitLab or someone else pushed some commits.
```terminal
git pull --rebase
```
.caption[
	Make sure you have no pending changes in your working directory before pulling.
	It is safe to run this command all the time, as there is no descrubtive behaviour by default
]

---

## Extra useful commands

To see what has changed in the file contents of your working directory.
```terminal
git diff
```
.caption[
	The markings `---` means line was removed, while `+++` means adding a line.
]

See a log of all recent commits
```terminal
git log --graph
```
.caption[
	You can also see visual graph history of commits in GitLab or with a GUI application
]

---
name: chapter-gitlab-ci

# GitLab CI

One of the killer features of Gitlab.

CI stands for [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) a common pracmtice of software development.

---

**GitLab CI**

---

## What this is capable of:

- Compiling websites with static site generators

- Make beautiful documentation using Gitbook, Sphinx, Mkdocs

- Automated Testing for software

- Resizing images

- Integrating content from different sources

- ...much more

Read more at [Gitlab Docs](https://docs.gitlab.com/ee/ci/)

---

## How does it work?

- You create a [gitlab-ci.yml](https://gitlab.com/pages/plain-html/-/blob/master/.gitlab-ci.yml) file of type HTML

- Then a "runner" server picks up your "Pipeline"

- Reading your `.gitlab-ci.yml` file wille execute your scripts in [Docker](https://www.docker.com/)

- After completeing your steps in the `yml` file, GitLab stores the results and publishing them on the web

#### See GitLab's example gitlab-ci.yml

GitLab has a list of example repositories for common static static site generators or HTML,
have alook at some of their `.gitlab-ci.yml` examples at: [gitlab.com/pages](https://gitlab.com/pages)

---

## CI build process flow

.full-width.center[
	![](images/gitlab-ci-workflow.png)
]

---

## CI Pipelines

Each time your commits get pushed, these are example tasks that can happen in a **Pipeline** on a **Runner**

You can monitor pipelines in the "Gitlab CI/CD" menu item.

---

## Example: mkDocs CI file

```yml
# What type of container should run this job (where the script will run)
image: python:3.8-slim

# This is the "job" name
pages:
  # This tells GitLab which group the "job" belongs
  stage: deploy

# Set any enviroment variables to be available inside the container
  variables:
    GIT_DEPTH: 1000

# These are the commands that will be run in the job
  script:
  	# This is a specific mkDocs command to make the HTML
  	- time mkdocs build --site-dir public

# Tells GitLab which folder to copy out of the "job" to send to another "job"
  artifacts:
    paths:
    # Select the public folder in this case, so it can be sent to GitLab Pages
    - public

only:
  	- master
```

---

layout:true

---
# Additional links
- [Learn Git by Atlassian](https://www.atlassian.com/git/tutorials/what-is-version-control) (nice descriptions and diagrams)
- [Learn Git by GitTower](https://www.git-tower.com/learn/)
- [Dangit, Git!](https://dangitgit.com/) (common git problems)

- [Fab Academy 2019 Tutorials Git cheat ](https://fabacademy.org/2019/docs/FabAcademy-Tutorials/week01_principles_practices_project_management/git_simple.html)
- [Fiore's recitation from 2019](http://fabacademy.org/2019/recitations/version-control/)
- [Recitation 2020 by Kris and Viktor.](http://academany.fabcloud.io/fabacademy/2020/recitations/version-control/)