2. Project management
This week we learned about version control and how to use Git. I have never used Git or created a repository, so I am a beginner. Therefore, to manage my fab academy weekly assignments and final project on Git Lab, I have to learn about Git from scratch. The assignment of this week is to build a personal website using website development tools and upload it to the class archive. In addition, I have to work through a git tutorial after learning about it and finally signing the student agreement.
This week assignment content:
I used the following resource to help me editing my site:
Jekyll Resources:
2.1. Student Agreement
Click here to enter the student agreement page.
2.2. Learn about project management
First of all, since I am a new in using git I have searched and learned about project management main terminology and basics. The following is a short explanation about what is a Repository, a Version Control System (VCS), and a git.
Repository
In fab academy course, all work will be documented in a repository. This method was chosen due to its capability of keeping history of the work saved each time in versions. Repositories can be set individually or by a group of people. Also, it can be set as a privte, which can be viewd and edited only by the author or as a public, which can be viewed by everyone.
Version Control System (VCS)
To write in the repository, a version control system (VCS) should be used. As its name implies, it is a type of systems that can keep versions of the user work every time it committed with a snipping message. The user cannot remove the old versions from the history path. In addition, it allows multiple users to manage, share, and cooperate multiple units of inforamtion. Advantages can be summarized by the following points:
- Make an archive of versions.
- Maintain versions historical inforamtion, for example auther, date and time.
- Enable collaboration, so people can share documents and data easily.
- Recover from accidental delections or edits.
- Conserve disk space because in each version, it saves only the changes from previous version.
Git
"Git" will be used as a version control system (VCS) since it is a free, efficient, fast, and open source tool. The course documentation will be posted online on "GitLab", which can be edited directly from "GitLab" online website using the text editor, or it can edited locally from a computer using "Git Bash" or "Git GUI".
2.3. Build my personal website
Initially, I have used the template provided on GitLab. Later on, I found many amazing online themes that I can download and push to my repository. The most one I liked and found it very orgnised and easy to navigate was Voyager theme from Jekyll themes. So, basically I went throught the following steps:
2.3.1. Build my personal site using MkDocs
For my first try in building a website, I chose MkDocs since it is the default template available on GitLab repository. As well as MkDocs is easier to learn than other static sites generators such as HTML. My Fab Academy documentation files were written in Markdown formmatting and configured using a YAML file.
What is Markdown ?
Markdown is a plain text formmatting syntax. I use it for web writing and editing to my repository. I chosed Markdown for my first try as it is lightweight markup language, easy to use by the beginners in web dueveloping, and since the available tamplate uses Markdown.
How the MkDocs static site generator works ?
The project template was ready made in GitLab so I didn't need to create a new one and set it up from scratch. However, I have searched about the way I can do it independently and try it myslef. The following steps explain the process.
Step 1: Installation
I installed Python and Python package manager pip on my system and used the following commands in Git Bash to confirm that they have been installed on my system:
python --version
pip --version
Command output is:
After that, I have installed the MkDocs package and shown its version by the following command:
pip install mkdocs && mkdocs --version
Command output is:
Step 2: Create a Project
To create and open a new MkDocs project page on my fab academy GitLab repository by typing the following commands:
mkdocs new my-project
cd my-project
ls
ls docs/
Project is created in the following repositroy location.
To list all project files type:
ls
ls docs/
Project is created with default configuration of type .yml file and docs directory that should contains all documentaion files. By default, the docs directory contains a doumentation page called index.md.
Step 3: Test the Web Page
I used atom software to see how the page will looks like before pushing.
Step 4: Create yml file in GitLab
Step 5: Local computer set up
To git user global setup:
git config --global user.name "Maryam Ali"
git config --global user.email "mariamaqeel96@gmail.com"
To generate and copy the ssh key for the local computer:
cat ~/.ssh/id_rsa.pub > /dev/clipboard
Then in gitlab online website, open settings > SSH Keys > paste the key > add a title for the key > press add key.
To create a new repository go to gitlab online website, open Projects > Your projects > choose the project you want to clone > press Clone > cope Clone with SSH
Write “git clone” and paste the copied clone in the Git Bash command window
git clone git@gitlab.fabcloud.org:academany/fabacademy/2020/labs/bahrain/students/maryam-ali.git
After cloning the project, repository folder will be created with the name and the location I set on my local computer. Now I am able to edit my documents locally from my computer and push them to my GitLab online repsitory. The following command will should be used to push changes to GitLab:
git add .
git pull
git commit -m 'update'
git push
2.3.2. Build my personal site using Jekyll themes
After learning about MkDocs, I looked for other themes on the internet and I liked to use Jekyll themes. Steps followed are explained below:
Step 1: Installing Jekyll
To install the Jekyll on my laptop (Windows), I followed this tutorial. Based on the tutorial, I should first isntall Jekyll and Bundler via:
gem install jekyll bundler
To check if Jekyll installed properly:
jekyll -v
To set up the server and build my site:
Jekyll serve && Jekyll build
I can copy and paste the server address shown in the command line to browse the generated page (i.e. http://127.0.0.1:4000/).
Step 2: Configiration settings
Add this part to the beginning of each weekly assignment.
Change the content of the .gitlab-ci file to:
Change urls in _config.yml file to (baseurl: “/2020/labs/bahrain/students/maryam-ali”) and (url: “http://fabacademy.org”).
Step 3: Default files created
myWebsite: main high level folder.
_posts: folder that will be used most of the time to add my work.
_site: final output of the website (static files), it holds the final version of your website. It will be updated for you, don’t modify anything inside it.
_config.yml: the setting for your Jekll website.
Gemfile: file used to store and specify all of the dependencies of your website. (e.g. the website theme).
Index.md: home page of your website.
2.4. Create a git tutorial
To create file directory:
mkdir file name
To open file directory:
cd file name
You can also open file directory by going to the file in your local computer and right click “Git Bash Here”.
To generate a list of files:
ls
To enter text editor:
vi
To produce a list of what you write already:
History
To get all files included the hidden ones:
ls –lah
To create a file without open it:
touch filename.md
To create file directory:
mkdir maryam
To create file inside a file:
mkdir maryam/imag/week1
2.5. Problem faced
Somtimes when I create a new page or add a new image, the jekyll cache is not produced automatically, so I should push the _site file manullly. To do that, I used the following command line:
git add -f _site