Skip to content

1. Project Management

I. Project Documentation

A. Introduction

The first assignment was to create a website which would act as a framework used to document and present the work I will complete during the next 5 months. My goal is to produce a layout that would allow each project to be accessed easily while ensuring the important content is displayed clearly. Seeing as I have no knowledge in HTML, CSS or any tool used to build webpages, I first focused on familiarising myself with the Static Site Generator (SSG) MkDocs.

B. MkDocs setup

Having already installed Python, I manually downloaded and installed Mkdocs on my computer using the following command in my terminal emulator:

1
pip install mkdocs

I then began editing the site template provided by FabAcademy, starting with the MkDocs.yml file. Changes to the initial file were minimal and only aimed to test the various features of an Mkdocs website. I defined the theme, fonts and colors of my documentation site (See code below). While easy to use, the framework provided by Mkdocs is quite rigid. I therefore decided to learn how to develop my own website using more rudimentary tools, namely HTML, CSS, Java etc. My goal is to achieve this throughout the next few weeks. I’ll be documenting my progress on the following page.

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
    # Replace the text below to customize your site
    site_name: Tarek Mahmoud
    site_description: Fab Academy documentation site for Tarek Mahmoud
    site_author: Tarek Mahmoud
    copyright: Copyright 2021 Tarek Mahmoud - Creative Commons Attribution Non Commercial

    site_url: http://fabacademy.org/2021/labs/barcelona/students/tarek-galal

    extra:
      social:
        # For other social icons at https://squidfunk.github.io/mkdocs-material/setup/adding-social-links/
        - icon: fontawesome/brands/linkedin
          link: "https://linkedin.com/in/tarekcmahmoud"

    theme:
      name: material

      palette:
        # try other colors https://squidfunk.github.io/mkdocs-material/getting-started/#primary-colors
        primary: amber
        accent: black
      font:
        # See available fonts at https://fonts.google.com/
        text: Inter
        code: Ubuntu Mono
      icon:
        logo: material/ethereum
      favicon: material/ethereum.svg
      features:
        - navigation.tabs
        - navigation.instant

    plugins:
      - search
      - git-revision-date-localized:
          fallback_to_build_date: true

    markdown_extensions:
      - extra
      - smarty
      - admonition
      - codehilite:
          guess_lang: false
      - toc:
          permalink: true

Once done, I added content to the relevant pages, using this guide to learn the Markdown Syntax.

C. Markdown Syntax | Cheat-Sheet

1. Text Styling

*italic* or _italic_

**bold**

***Bold & Italic***

~~Strikethrough~~

1
2
3
4
5
6
#      Heading 1
##     Heading 2
###    Heading 3
####   Heading 4
#####  Heading 5*
###### Heading 6*

2. Layout Formatting

1
For a code box, wrap text with 3 (`)

For a blockquote, include a ‘>’ at the start of a line

D. Work Environment

Computer | Macbook Pro 2017 Text-Editor |

Site Name Description
AdobeColors Color Selection & Exploration Tools
W3Schools Guides and Tutorials for web dev tools
Jamstack Web Hoster Listing SSGs
dotCMS Basic Markdown Syntax Guide
Material for MK docs Guide for MkDocs Material theme
Mozilla Dev Net Mozilla WebDev Guides

II. git

A. Description

Git is a distributed version control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files. Its goals include speed, data integrity, and support for distributed, non-linear workflows.

GitStructure

B. Installation

Git was already availale on my Macbook as I had Xcode installed. I checked its version using:

1
$ git --version

The version of git installed on my computer was 2.24.3, a couple editions behind the latest release 2.27.0. I upgraded it using Tim Charper’s installer.

I then generated an SSH key with a size of 2048 and added its public version to my gitlab account. Key generation was achieved using:

1
$ ssh-keygen -t rsa -b 2048 -C "tarekcmahmoud@gmail.com"

Once completed, I cloned the provided online repository to my system with:

1
$ git clone git@gitlab.fabcloud.org:academany/fabacademy/2021/labs/barcelona/students/tarek-galal.git

To familiarize myself with the basic git commands and procedures. I completed the tutorial found on git’s official site noting all commands I deemed to be important at my level, all of whoch can be foind in the below cheat sheet.

C. Git Commands Cheat Sheet

1. Creating or Importing a New project

1
2
3
$ tar xzf project.tar.gz
$ cd projectdirectory
$ git init
Chain of terminal commands allowing to create a new git project in a specified directory.

1
$ git clone repository/link/
Creates an exact copy of an online repository

2. Making and Pushing Changes to a Project

1
$ git status
Summarises the changes made to the offline repository by comparing files to those on the online repository.

1
$ git add file1 file2 file3
Adds specified modified/untracked file to staging area.

1
$ git add .
Adds all modified/untracked files to staging area

1
$ git commit -m "Commit message"
Commits changes placed in the staging area to the offline repository.

1
$ git commit -a
Commits all untracked files to the offline repository.

1
$ git push
Push commited changes to the online repository.

3. Tracking changes

1
$ git diff
Displays changes made but not added to index.

1
$ git diff --cached
Displays changes about to be commited.

1
$ git log
Displays history of changes made to online repository.

1
$ git log -p
Shows Complete differences for each of the past changes.

1
$ git log --stat --summary
Overview of all modifications made.

4. Branching

1
$ git branch
List of existing branches.

1
$ git branch branchname
Creates new branch with specified branch name.

1
$ git switch branchname
Switches to specified branch.

1
$ git merge branchname
Merges current branch with specified branch.

1
$ git branch -d branchname
Delete specified branch.

5. Collaboration

1
$ git pull
Fetches changes made in a remote branch and merges them with local branch.

D. Managing my repository

FabAcademy provided us with our own repo containing the base files for us to set up our mkdocs documentation site. I cloned the repo to a folder on my computer using the following sequence of command:

1
2
3
4
5
6
7
1. $ cd repo/directory/path/oh/yeah/baby

      # Sets the active terminal directory to the one where I wish to copy my repo.

2. $ git clone https://gitlab.fabcloud.org/academany/fabacademy/2021/labs/barcelona/students/tarek-galal.git

      # Copies the repo to the specified directory.

Having made the modifications I wanted, I then pushed the local copy of my repository to its remote site on gitlab through the following sequence of commands.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
3. $ git status

      # Displays a list of files that have been modified in the working directory.

4. $ git add modified_files

      # places the specified file to the staging area.

5. $ git commit -m "Commit Message"

      # Commits the changes to the local repository.

6. $ git push

      # Pushes and applies all changes to the remote repository.

E. Summary

From this introduction to distributed version control, I can tell that it is a great system to seamlessly collaborate and share projects with a great audience. It will take some time to get used to. I will need to make sure I do not make any mistakes pushing changes to the remote repo as this might brake it. Below are a few rules I’ll follow to make sure things run as smooth as possible. I’ll update them throughout the course with new things I’ll learn.

Verify what files have been modified

Always check what files have been registered as altered by git before proceeding to a push, using git status.

Add files individually

Refrain from using “git add .” to stage multiple files as certain unwanted modifications might end up being pushed. Instead, use “git add file1 file2 file3 .... fileX”.


Last update: June 16, 2021