Version Control - Fab Academy 2021 Recitations

### Recitation

_Monday January 29th, 2024_

# Version control & GitLab

**Presented by Julian Gallimore**

---

# Agenda

1. [Fabcloud services & how to login](#chapter-fabcloud)

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

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

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

1. [Setup mkdocs framework](#chapter-setup-mkdocs)

---
layout: true

**Fab Cloud platform**

---
name: chapter-fabcloud

# .logo_tiny[![](images/fabcloud_logo.png)] FABCLOUD

* [Fablabs.io](https://fablabs.io) - Network map of FabLabs & for universal logins
* [gitlab.fabcloud.org](https://gitlab.fabcloud.org/) (self-hosted) - Git repository & website hosting
* [chat.academany.org](https://chat.academany.org/): self-hosted Mattermost communication tool
* [nueval.fabacademy.org](https://nueval.fabacademy.org/): Student evaluation tool

_FYI: All self-hosted by Fab Foundation (so we secure the data)_

---

## Fablabs.io

- Online platform that maps the FabLab network world-wide
- Forums for engaging with the wider FabLab network
- Provides the user account logins for our platforms GitLab & Nueval
    ie. "Login with Fablabs.io"

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

---

## What is GitLab

GitLab is a web-based tool that provides a Git-repository hosting plus extra features, developed by GitLab Inc.

* Similar to GitHub, Bitbucket
* Source code hosting your Git projects, plus:
  * Issues tracker
  * Collaboration tools (ie. Merge requests, Review apps, etc)
  * Website hosting (GitLab Pages)
  * CI pipeline for automatic project building/compiling
* We self-host our own version of Gitlab
  * We host all the Git repositories related to the academies
  * Where you will can edit YOUR documentation website

> More info about GitLab https://docs.gitlab.com/

---
layout: true

# GITLAB

---
class: center

## HOW TO LOGIN

Follow along with me with me

.caption[
  **New students**, find your access details in your email, subject:
  <br> "_Fab Academy 2024 accounts access_"
]

---
class: center

## 1. Start at GITLab.fabcloud.org

---
class: center

## 2. Login at FABLABS.io

<img src="images/fablabs-login.jpg" width="300" />
.caption[
  Use your username/password we provided. Use "Forgot password" if you have trouble. 
  <br>_Do not create a new account, contact coordination instead_
]

---
class: center

## 4. (optionally) Grant access to GitLab

---
class: center

## 5. Success! GITLAB Dashboard

---

## Gitlab & FabAcademy structure

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

#### What we do with Gitlab

1. **Student documentation** under version control
1. **Host** student websites (using [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/index.html)
1. Track all [groups](https://gitlab.fabcloud.org/academany/fabacademy/2024/labs) of students, labs, instructors
1. Ask and **discuss class questions** using [issues](https://gitlab.fabcloud.org/academany/fabacademy/2024/class/-/issues)
1. Use Gitlab as a **project management** tool (issues, milestones, boards)

---
class: middle, center

### Fab Academy GitLab structure

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

---
class: center

## Find your project

From the GitLab dashbaord, you should see your student documentation
website repository.

#### Example student URL:

gitlab.fabcloud.org/academany/fabacademy/2024/labs/**hosted-lab-name**/students/**my-name**

#### Example all students repository for a lab:

gitlab.fabcloud.org/academany/fabacademy/2024/labs/**hosted-lab-name**/students

---
class: middle, center

### Demo the GitLab interface

* Project student repository
* Sidebar links
* How to edit a file
* Review CI (project builds)

Visit
[gitlab.fabcloud.org/academany/fabacademy/2024/](https://gitlab.fabcloud.org/academany/fabacademy/2024/)

---

**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
- View history of all commits (who/when/what changed)
- Revert/restore past changes (good if anything breaks)
- Push commits (changes) to remote central repo (upstream/origin)
- Multiple locations can sync their changes with origin

[Learn Git by Baeldung](https://www.baeldung.com/git-guide)

[Wikipedia.org/wiki/Git](https://en.wikipedia.org/wiki/Git)

---
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 commit a `.gitlab-ci.yml` file in your repo (see [HTML example](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-html/-/blob/main/.gitlab-ci.yml))

- Push the commit

- Then a "runner" server will pick up your commit and start a "Pipeline" process for that commit

- Reading the `.gitlab-ci.yml` file will execute the above script in a [Docker](https://hub.docker.com/search?q=) container.

- After completing the steps in the `yml` file, GitLab stores the results (or publishes the file on the web for "pages" job)

.caption[
  Keep in mind, only the most recent Pipeline matters. So older pipelines from previous pushes/commits that failed can be ignore if the most recent commit passed successfully. 
]

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

---

## CI build process flow

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

---

#### Example CI: publish plain HTML files

```yml
# What type of docker container should run this job (ie. simple linux or python, php, etc)
image: busybox

# This is the "job" name (needs to be "pages")
pages:

# These are the commands that will be run in the job
  script:
    # (ie. for HTML nothing need done, so we just run a command saying nothing)
    - echo "nothing to do"
    
    # (ie. but for MkDOCS we need to build the HTML from markdown)
    - pip install -r requirements.txt
    - mkdocs build --site-dir public

# Tells GitLab which folder to keep after finish building
  artifacts:
    paths:
      # For GitLab Pages, we need a folder called "public" with html files
      - public
  
  # Defines when to run this "job" when a commit is pushed 
  rules:
    # (eg. only for the default branch)
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

---

## CI examples

Keep in mind, to deploy to GitLab Pages there needs to be a folder called "public" with the HTML to publish.

* [Mkdocs student template](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-mkdocs) (copy all the files if you want mkdocs)
* [Example idea: Using NPM with framework example](https://gitlab.fabcloud.org/-/snippets/120) (React,Vue,Angular,etc)
* [Example idea: Using NodeJS install and cli TailwindCSS](https://gitlab.fabcloud.org/-/snippets/117)
* [Example: Plain HTML example ](https://gitlab.fabcloud.org/-/snippets/118)
* [Current HTML student template](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-html)

---

### Demo GitLab CI interface

Visit
[gitlab.fabcloud.org/academany/fabacademy/2024/site](https://gitlab.fabcloud.org/academany/fabacademy/2024/site/-/pipelines)

---

**Local GIT**

---

## Setup Git locally

---

## Install Git on your computer

* _MacOS_: using Homebrew
  ```terminal
  brew install git
  ```

* _Ubuntu_: 
  ```terminal
  apt install git
  ```

* _Windows_: See [git-scm.com/downloads](https://www.git-scm.com/downloads) for examples

---

## 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 you push.

#### Generate your [SSH Key](https://docs.gitlab.com/ee/user/ssh.html#generate-an-ssh-key-pair)

- Linux and MacOS

```terminal
  ssh-keygen -t ed25519 -C "ssh-for-fabcloud"
  ```

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

---

### Add the public key to your GitLab profile

[See GitLab docs](https://docs.gitlab.com/ee/user/ssh.html#add-an-ssh-key-to-your-gitlab-account)

Copy the **PUBLIC key** only, from where you just created the keys:

```terminal
  cat ~/.ssh/id_ed25519_fabcloud.pub
```

---

## 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 <git@gitlab.fabcloud.org/url-to-git-repo-here> <name-of-folder>
```

---

## 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 user.name "Your Name"
git config 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).
	Keep in mind if you have other Git accounts when using the `--global` parameter to change the email for all repos.
]

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

---

## About Git staging process

The diagram below illustrates the different areas in your local git repository.
.full-width[
  ![](images/git-staging.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
```

---

## Check errors when pushing

Example what an error looks like when pushing in GIT.
.full-width[
  ![](images/git-push-error-size.png)
]
.caption[
   This error is GitLab limiting you to 10MB per commit. Amend your previous commit to remove some larger images/files.
]

---

## 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 destructive behavior by default
]

To reset your local repo to match what is in GitLab (removing any local changes and pending commits). This is good way if things are just not working and you are stuck.

```terminal
git reset --hard origin/main
```

---

## 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
]

---

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/)

---
layout: true

**Example: Use markdown & Mkdocs for website**

---
name: chapter-setup-mkdocs

## Manually working with HTML files

Working with HTML files, shared parts like the navigation bar would need to be copied to each file manually. See the two files below, the navbar need to be same.

---

## Using Markdown for HTML

* A markup language which allows easy to read and write plain-text document
* Tools, like mkdocs, exist to convert markdown to valid HTML in a predictable manner

---

## About MkDocs

* Tool, called a static site generator, made for project documentation
* Documentation is mainly written in Markdown
* Install themes to have a different style of websites
* Then can be customised with theme options
* Builds your HTML site from the markdown and theme
* Can also add extra plugins & extensions to add features to your site

See more at [mkdocs.org](https://www.mkdocs.org/)

---

### Basic files for a Mkdoc project

* **mkdocs.yml** (configuration file for website)
* **requirements.txt** (use to install mkdocs, themes, plugins)
* **docs/** (folder for all markdown files and images)
    * eg. _docs/index.md_
    * eg. _docs/assignments/week03.md_
    * eg. _docs/images/profile.png_
* **.gitlab-ci.yml** (CI file to build mkdocs website and publish HTML)

### Interested?
* check out the template: [academany/fabacademy/templates/student-template-mkdocs](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-mkdocs/)
* Use your project WebIDE, or locally, to copy all the files listed above
* Read how to add pages [on mkdocs website](https://www.mkdocs.org/getting-started/#adding-pages)
* check out installed [material theme](https://squidfunk.github.io/mkdocs-material/setup/)

<br>
#### Time for a Demo?

---

## Typical CI errors

### CI does not know where to get the theme

```terminal
$ mkdocs build --site-dir public
ERROR    -  Config value: 'theme'. Error: Unrecognised theme name: 'sunshine'. The available installed themes are: material, mkdocs, readthedocs
Aborted with 1 Configuration Errors!
```

> Remember, add the theme to the `requirements.txt` file with a version number

---

## Typical CI errors

### Possible mistake in _mkdocs.yml_ file or indentation:

```terminal
$ mkdocs build --site-dir public
Error: MkDocs encountered an error parsing the configuration file: mapping values are not allowed here
  in "/builds/academany/fabacademy/2024/example/site/mkdocs.yml", line 26, column 10
```

> Check the last commit, and revert the change, or review the mkdocs.yml vs the mkdocs/theme docs. Also check the file is valid yml (ie. [yamllint.com](https://www.yamllint.com/))

---

**Example: Using Hugo framework for website**

---

## Next level: [Hugo framework](https://gohugo.io/)

If you'd like a bit more advance framework vs mkdocs, one option is Hugo:

* Easy to install, with a simple binary file to run
* Can use markdown for all pages
* For customizable than mkdocs
* Easy custom theme or pre-built at https://themes.gohugo.io/

<br >

See [getting started docs](https://gohugo.io/getting-started/) for more info on Hugo:

Example template at [academany/fabacademy/templates/student-template-hugo](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-hugo)