Project Management

The aim of the project management week assignment was learning how to use Git, and building a personal site in the class archive describing me and my final project.

At this point, did not know what to make as a final project yet, but I was very excited about learning Git and creating a website that could accommodate all the content in the best way possible.

Learning Git

As seen in the wikipedia, Git is a free and open source distributed version control system for tracking changes in computer files and coordinating work on those files among multiple people.

In order to start practicing with Git, I visited the Git Project website.

Most of the information available in the Git Project website, was nicely exposed by Fiore during the first half of his version control recitation. Anyway, I enjoyed browsing the Git Project website and finding an astonishing amount of official resources to continue learning Git.

I could not resist to click the “Learn Git in your browser for free with Try Git” link at the welcome page, and if you are reading this, I really recommend you to do the same .

The Code School website where the “Try Git” course was located is also very recommendable.

After I earned my tryGit badge, I watched the second half of Fiore’s version control recitation, and then I felt confident enough as to install Git in my computer.

Installing Git

In order to install Git in my laptop, I needed to download it first.

So, I went back to the Git Project website, and I browsed to the downloads page in search for the latest version available for Mac at that time. Once there, it was fair simple to find it, as the website seemed to recognize the most suitable version for my OS. I just had to click the “Download 2.16.1 for Mac” button, and the download started.

When the corresponding mountable disk image (.dmg file) was completely downloaded, I double-clicked it. This prompted a new tab on Finder with the installation package (.pkg file) on it .

Then, I double-clicked the *.pkg file and the installation process started! From there on, I just had to follow the installation instructions until the installation process finished.

The first thing I did after Git was installed in my computer, was opening the Terminal) application in my computer to double-check that the Git installation was correctly done.

Once the Terminal window was open, I typed:

$ git --version

And this confirmed that the version installed in my machine was the latest:

git version 2.16.1 (Apple Git-98)

Then, I followed the instructions at “First-Time Git Setup”, and I set my user name and email address by typing:

$ git config --global user.name aitoraloa
$ git config --global user.email aitoraloa@gmail.com

This last step was very important, because every Git commit done later would be using that identification information, and these details were going to be immutably baked into the commits.

After my identity was created and checked, the next step was generating a public SSH key so I could link my computer to my remote Fab Academy student repository in the Fabcloud server.

SSH (Secure Shell) is the network protocol that was going to allow me to access my remote repository during the whole Fab Academy in a secure way. Therefore, I needed to generate a public SSH key pair in order to add the SSH public key to GitLab account later.

In order to generate the SSH key, I used the Terminal program again:

$ ssh-keygen -t rsa -C "aitoraloa@gmail.com” -b 4096

And the terminal window prompted where the SSH key pair had been saved in my computer.

Generating public/private rsa key pair.
Enter file in which to save the key (/Users/aitoraloa/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/aitoraloa/.ssh/id_rsa.
Your public key has been saved in /User/aitoraloa/.ssh/id_rsa.pub.
The key fingerprint is:
45:b1:86:76:5d:f9:a3:ba:9b:92:00:30:9a:2e:b0:b0 aitoraloa@gmail.com
The key's randomart image is:
+--[ RSA 5196]----+
| .+o.o.          |
| .=. .           |
| * .             |
| . + .           |
| S . . .         |
| o E             |
| ..=o.           |
+-----------------+

Then, in order to access the generated SSH key, I typed:

$ cat ~/.ssh/id_rsa.pub

And the public key prompted:

$ cat ~/.ssh/id_rsa.pub
ssh-rsa ABBBB3NzaC1yc2999990000ccc222lllgggQCw3qxUmh4/A0pL9n8H7f4D3CVd21AZZZ443DY/RkDIj5fjaldkjnotiu990903j4lMSO023NLZGUTWOPBN90SkZK2hpv7tkRkwuPSerI7h7hAKhBop0nmRVbjE31EiaHgq/0Jxqphz/6nwDxC89wkxYrLLCy96HxcGEJUzkXsNW0XwhxkO+7o62fl2HOP[CZVLKJDREALFRTIQ0A9BQWLKJMGTu37g+lUOIZASUYZQsFYhQEJHvIxKb43plk+UEyQtnK+sP7LqyMILKeyqjfl9FG2K48GAJ7V73xj4860t+2YC0d/2QGNwqxFvbnmhax/zj/07gkn385a aitoraloa@gmail.com

I selected the public key in the console, and I copied it to the clipboard.

Then, I went back to my user account in GitLab and navigated to “Profile > User Settings > SSH Keys”, where I pasted the SSH public key (under “Key”).

Then, I clicked the “Add key” green button, and the public key was added to my GitLab account.

Once the public SSH key was saved, the next thing I to do was initializing Git in my computer.

But first, I created a local repository in the desktop using the terminal window:

$ cd ~/Desktop/
$ mkdir aitor.aloa

And I navigated to it:

$ cd ~/Desktop/aitor.aloa/

Once in my working repository, I initialized Git by typing:

$ git init

At this point, I had a Git repository initialized in my laptop, and I could securely connect to my Fab Academy student repository in the Fabcloud server.

The next step was cloning my remote repository in GitLab to my local Git installation.

In order to do that, I needed my remote repository’s URL, so I went back to my GitLab account, and I navigated to “~/labs/barcelona/students/aitor-aloa > Overview > Details”.

Once there, I copied my remote repository’s URL in the clipboard.

Then, I went back to the Terminal program, and I used the URL that I had just copied, along with the command “git clone” in the terminals window’s command line:

$ git clone git@gitlab.fabcloud.org:academany/fabacademy/2018/labs/barcelona/students/aitor-aloa.git

And my local Git repository and my remote repository were sync! Yeah!

It was time to start moving files from the local repository to the remote repository in order to make my personal website available online but… I needed to build one first!!

Building my personal website

I have worked as web designer before, and HTML was one of the languages I learned during that period. Unfortunately, in the last few years I have not done web design at all, so I though that developing my Fab Academy webpage from scratch using HTML would be refreshing.

A couple of weeks later, I realized that (even using Sublime or Brackets as text editors) writing the HTML code directly would be unreasonably time consuming. Specially, taking into account the huge amount of things that I had to learn/make during the Fab Academy course, and how extensively I did wanted to document each weekly assignment.

Despite I really liked the welcome page that I had created for my Fab Academy website using HTML, CSS (Cascading Style Sheet) and JS (JavaScript), the amount of time I spent working on it was excessive, so I decided to change the plan completely.

Once I had discarded the “html-from-scratch” option, the logic alternative seemed to be using one of the many open-source CSS frameworks available online.

As seen in the wikipedia, a CSS framework is pre-prepared software framework that is meant to allow for easier, more standards-compliant web design using the CSS language.

Among the dozens of CSS Frameworks available, there were a couple of them that stood out above the rest: Bootstrap or Foundation. From the two, Bootstrap seemed to be incredibly popular. Thanks to that, there were a lot of resources available (tutorials, extra plugins, themes, etc).

In any case, while getting to know Bootstrap better, I also found out about static web pages and Markdown. After searching for information online, I still needed to understand the whole static web generator thing better, but it was pretty clear that using a static site generator had much more advantages for me than making a dynamic CMS site: less complexity, faster serving, more security, improved scalability, and version control. Just what I needed!

The amount of static site generators available at that time was astonishing, and it was really hard for me to decide which one to go for. Jeckyll, Hugo or any of the first options at StaticGen seemed really good choices to continue the static site creation path.

Among all the options available at StaticGen, I finally opted for using GitBook.

GitBook is both an online platform for writing and hosting documentation, and an open source book format and toolchain for building beautiful books using GitHub/Git and Markdown.

In my particular case, I was planning to write the documentation locally using Markdown (although I finally used Dropbox Paper, which works as Markdown editor but on the cloud). Then, this Markdown formatted documentation would be hosted (along with images, PDFs, etc.) in my local repository, and pushed to my remote repository every time I wanted to update my Fab Academy student website.

The point here was that I was going to use GitBook’s command line tool, but I was not going to use GitBook’s platform output the content as a website. I was going use GitLab instead.

In any case, I signed up myself in GitBook and I followed the whole registration process.

Once I had verified my GitBook registration, I created a “new book” (or repository) called “test” :

Then, I used GitBook’s “Clone and push changes with Git” option to copy the URL of the new book/repository that I had just created.

And finally, I went back to the terminal window, and I cloned the repository in GitBook to my local git repository by typing in the command line:

$ git clone https://git.gitbook.com/aitoraloa/test.git

Which created a second working directory called “test” in my Git installation.

At that point, I had two working directories in my Git installation. One empty directory named “aitor-aloa” and connected to GitLab; and another working directory named “test” and connected to GitBook that contained three Markdown files: README.md, SUMMARY.md and chapter1.md.

As the files in the “test” working directory were structured as to be published as a GitBook document, I moved these files from the “test” directory to the “aitor-aloa” directory.

Then, I used Brackets text editor to update the SUMMARY.md file in the “aitor-aloa” working directory, so the content of this summary file matched the Fab Academy 2018 schedule.

Once the file SUMMARY.md was updated, I created three new markdown files for the three weekly assignments that I was going to publish at that moment (About me, Principles and Practices, Project Management), and I saved them in the “aitor-aloa” directory.

Note that I also deleted the file “chapter1.md” from the “aitor-aloa” directory.

So far so good! I had the file structure for my GitBook-based Fab Academy Student page ready in my local repository, and I could start moving files to my remote GitLab repository.

In other words, I could start developing my Fab Academy documentation by adding content to the markdown files that I had already in my working directory, I could create new markdown files for the weekly assignments as the Fab Academy progressed, and I could use Git to send all the documentation generated locally to my GitLab repository, so my public Fab Academy student website would be regularly updated.

Editing and creating markdown files

Markdown is a lightweight markup language with plain text formatting syntax that allows non-programming types to create documents, rich text, or HTML markup using any plain text editor.

At the moment of this writing, the amount of markdown editors available both for macOS, Windows or Linux was huge. From apps like Mou, Typora, Caret or Haroopad, to in-browse editors like StackEdit or Dillinger, going through many of the most common text and source code editors like Sublime, Brackets, Atom, MacVim, Emacs and many more.

Despite I would have loved to test any of the apps or in-browse editors available (and I will probably do it in the future), I preferred to keep the things simple and continued using Brackets as I did before when I edited the SUMMARY.md file.

Anyway, I found out that there was a Brackets extension for previewing markdown files that seemed really useful, so I followed the installation instructions available at the extension’s download page, and a few minutes later I was already using it (along with a markdown cheatsheet) to preview and edit the markdown files in my working directory.

On the other hand, creating new markdown files with Brackets for any of the Fab Academy weekly assignments that I was already documenting (or that I was about to document) was very simple.

As simple as opening a new file by clicking “File > New” in the main menu bar, and saving it as “FILENAME.md” later, where FILENAME was the name of the assignment and the *.md extension established that the file was a Markdown file.

Once the whole markdown files edition and creation thing was clear, it was time to start using Git to send these files to my Fab Academy student repository.

Using Git to update my remote repository

The first thing I did in order to start sending the files from my local repository to my GitLab repository was going back to the Terminal application and making sure that I still was in the right working directory by typing:

$ cd ~/Desktop/aitor.aloa/aitor-aloa

Then, I double-checked the content inside the working directory by typing:

$ ls

Which basically prompted the name of the files within that directory:

README.md SUMMARY.md about_me.md principles_and_practices.md project_management.md

Then, I checked the status of the Git repository by typing:

$ git status

And the terminal window prompted:

On branch master
Your branch is up to date with 'origin/master'.
Untracked files:
(use "git add ..." to include in what will be committed)
README.md
SUMMARY.md
about_me.md
principles_and_practices.md
project_management.md
nothing added to commit but untracked files present (use "git add" to track)

Meaning that I had several files that had been added to my working directory but that these files needed to be “stagged” (added to the staging area) so they could be “committed” later and sent to the local Git repository.

Therefore, I added all the files to the staging area by typing:

$ git add .

Then, I used the “git status” command again, and the terminal window prompted:

On branch master
Your branch is up to date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD ..." to unstage)
new file:   README.md
new file:   SUMMARY.md
new file:   about_me.md
new file:   principles_and_practices.md
new file:   project_management.md

Meaning that the files had been added to the stage area, and I could proceed with the commit.

In order to make my first commit, I typed:

$ git commit -m "1st commit”

And the terminal window prompted:

[master 4525015] 1st commit
 5 files changed, 41 insertions(+)
 create mode 100644 README.md
 create mode 100644 SUMMARY.md
 create mode 100644 about_me.md
 create mode 100644 principles_and_practices.md
 create mode 100644 project_management.md

Meaning that the files had been committed, and the data was safely stored in my local database.

Finally, I just needed to send the files in my local Git repository to my remote GitLab repository.

In order to do that, I typed:

$ git push origin master

And the terminal window prompted:

Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (5/5), 1.98 KiB | 1.98 MiB/s, done.
Total 5 (delta 0), reused 3 (delta 0)
To gitlab.fabcloud.org:academany/fabacademy/2018/labs/barcelona/students/aitor-aloa.git
0ad001b..4525015  master -> master

Meaning that the files had been sent to the remote GitLab repository and… so it was! ;)

Making my website visible

At this point the only thing I have left to do in order to make my website visible for everybody in the Fab Academy students directory, was creating a valid GitLab CI configuration.

I was not sure what did that exactly mean but, fortunately, Fiore’s lecture and the material available at GitLab Documentation site, helped me to solve the majority of the doubts I had.

After few minutes processing the information, I arrived at the conclusion that I needed to add a .gitlab-ci.yml file to the root directory of my GitLab repository, and configure it to use a runner, so each push o commit would triggered my CI pipeline.

In order to do that, I navigated to the main page of my GitLab repository and I pressed the “+” symbol available there, so I could add a new file.

In the new page that opened, I added the name .gitlab-ci.yml under “master/File name”.

And instead of using any of the templates available at the top dropdown menus (as explained during Fiore’s lecture), I pasted the YAML code that I had copied from the “Example GitBook site using GitLab Pages” repository, as it contained the definitions of how my project should be built.

Then, I updated the "Commit message” at the bottom of the page to “Add CI”, and I pressed the “Commit changes” button in order to save the .gitlab-ci.yml file.

Finally, I went back to my GitLab’s repository main page, and the newly committed file was there, along with all the markdown files that I had previously “pushed” from my local repository.

And, a few minutes later, my GitBook-formatted Fab academy student page was online.

From that point on, I just needed to copy the .gitlab-ci.yml that I had created in GitLab to my Git repository using the terminal window:

$ git pull origin master

So my local branch would be up to date with 'origin/master’.

And continue updating my work!

What I have learned?

The amount of information handled during this first week was a bit overwhelming.

Anyway, it was very satisfying to see how everything ended up fitting and working well, despite all the initial frustration while trying to understand the whole version control procedure.

Maybe, I did not refresh my HTML skills as initially intended to do, but I learned a lot about the new website development tools available, which will probably be very useful or more.

I still had to get used to all new things I learned but… it was just a matter of time and practice!

Issues that I had

Actually, I had not remarkable issues.

All the resources provided during the recitations and available online for each of the exercises that needed to be completed during this week's assignment were extensive and really really helpful.

Apart from a few error responses in the console due to errors while typing the commands, I guess that the main issue was understanding what I was doing in some of the instances where I was a total newbie.

Tools used

• MacBook Pro with macOS High Sierra v10.13.3 installed
• Git v2.16.1
• GitLab
• GitBook
• Terminal v2.8
• Brackets v1.12