1. Project Management and Documentation#

Week’s introduction#

We stated the week with an introduction to Git which I was already formalized with in my past 2 years in CS. This service needs no introduction since it is the easiest way to work and allow other contributors on your open-source project.
You can showcase your work to attract recruiters, so the more projects you did the higher your chance to be recruited.
It also allows you to use a simple text editor Markdown to document your work, comments, user comments, etc.

Get Started with Git#

Environment#

All the work and documentation done on this platform will be on Mac/Linux since they both share some UNIX heritage; similar command-line shell(terminal), identical file structure. If you have Windows, I advise you to install Linux either in a virtual machine or directly on your pc, which will make your life significantly easier.

Git install#

To get started with git, you need to install it. You can check if git is already on your device by typing this command in your terminal:

$ git --version

If you get something like this: git: command not found .That means that this part is for you.
You can either install this through your terminal:

  • Linux RPM-based(Fedora,CentOS,Etc.)
$ sudo dnf install git-all
  • Linux Debian-based(Ubuntu,Kali,Etc.)
$ sudo apt install git-all
  • MacOS Homebrew
$ brew install git
  • MacOS MacPorts
$ sudo port install git

Or you can install it on macOS via a binary installer.

Git configure#

Now that you’ve installed git, we can set it up, we need to set it up, so you can dive directly into your new project.

  • Firstly, you need to add your GitHub/Gitlab* username: 
$ git config --global user.name "your_username"
  • Secondly, add your GitHub/Gitlab email address: 
$ git config --global user.email "name_surname@gmail.com"
  • Lastly, you can check if everything is right: 
$ git config --global --list

Now you are set to begin. You can either start a new project or contribute to an existing one.

*: preferably set your Gitlab using GitHub (if you already have one) this way will have the same username/email address.

Git start#

To start your work, you have to create a new repository/project:

  • Gitlab :
    1. Go to Homepage
    2. In the top-right corner, Choose a new Project
    3. Fill the relevant details
  • GitHub :
    1. Go to Homepage
    2. On the left sidebar, Choose the green box new
    3. Fill the relevant details

Git contribute#

To contribute to your own work (if you have created your new repository) or to someone else’s work. You have to authenticate with either SSH (one time authentication) or HTTPS(each time authentication), this way you can clone his repository.

Authenticate with SSH#

SSH uses two keys, a public key and a private key.

  • The public key can be distributed.
  • The private key should be protected.

To generate an SSH key pair:

  1. Go to your terminal
  2. Run this command ssh-keygen -t followed by the key type(we use ed25519) and an optional comment
ssh-keygen -t ed25519 -C "<comment>"
  1. After receiving the message bellow, click on Enter
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/macpro/.ssh/id_ed25519):
  1. Now all you have to do is protect your key using a passphrase that is hard to guess
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

Enter same passphrase again:

Now all is left to do is to add the public SSH key to your GitHub/Gitlab

Authenticate with HTTPS#

To authenticate with your HTTPS key, you have to be already logged in on your text editor to GitHub/Gitlab. Then all you have to do is to clone the project you are willing to work on.
To do so on:

Useful Git commands#

Command Description
git code . Open vs code
git status Show file status
git status -s show short file status
git add Add the particular file to staging area
git add . Add all the file to the staging area
git commit –amend Add these changes to the last commit (will have to use vim editor)
git commit -m “message” Commit the files in the staging area
git commit -am “message” Will commit without adding the file to the staging area
git checkout – will restore the file from the last commit
git checkout -f All the files will be replaced with last commit
git checkout -b Create a branch
git branch To see the branches
git branch -d To delete a branch
git branch -v will show the branch and its last commit
git branch –merged will show the branches that are merged
git branch –no-merged will show the branches that are not merged
git merge while in a branch you can merge another branch
git log Show all the commits
git log -n n can be replaced by any number “will show last n commits”
git log -p Will show detailed description of the commits
git log -p -n use of n is similar as described above
git log –stat will show short detailing of the commits
git log –stat -n use of n is similar as described above
git log –since=n.days commit of last n days/weeks/months “days can be replaced by weeks,months”
git rm –cached will remove to file from the tracking area
git rm -rf will uninitialized the current repository
git rm will delete the file
git mv to Rename the file
git clone Cloning a repository in the current folder
git clone folder-name Cloning the repository in the given folder name (Folder will be created by itself)
git config –global alias. ‘old command’ while create an alias command for the given command
git remote Show all the name of remote repository
git remote -v Show all the path (fetch/push) of the remote repository
git remote add url Add a remote repository
git remote rm To remove a remote
git push To push a branch to remote repository
git push :
git reset HEAD To move to a previous commit

Documentation#

Documentation is an essential process for every project to control the quality of your work, organize it, keep a record of every step you took which can establish a thought process and discover when an idea was made. And proper documentation ensures a clear communication specially when working in teams, enabling collaborative research and guaranteeing the transmission of knowledge.
Here are some great tips to secure near perfect documentation:

Markdown#

Markdown is a popular lightweight markup language widely used for various purposes, including documentation. It is easy to learn and read, so you can stop worrying about syntax and complex formatting and focus more on what you are writing. It is also compatible with almost every text editor, so you can work on your code/project and documentation on the same application.
Here is a cheat sheet that covers nearly everything essential you need to know:

Syntax Example
*italic* and **bold** italic and bold
[linked text](https://www.youtube.com/) linked text
Title [reference](module1#Marldown) Title reference
x<sup>2</sup> + x<sub>1</sub> - 1 x2 + x1 - 1
![](/picture/path..) Picture
#Heading First heading
##Heading Second heading
1. item1 2. item2 Ordered List
*item *item Unordered List
2 spaces Next line
> Blockquotes > Blockquotes
'''Code spanes''' Code spanes
He has <span style="color:red">red</span> hair. He has red hair.

Effectiveness#

To have an efficient website, you have to manage loading times, storage space, and mobile optimization.
One way to solve these problems is to compress your videos and pictures.

Compressing Pictures#

JPG format is great for compression because it uses lossy compression, which significantly reduces file size by discarding non-essential image data, while retaining good image quality for photographs and complex images.
Even if the image is already in this format, you can usually still make it take up less space.
Using Gimp we open our picture then export it as JPEG:

Export it, then choose its quality by defining the percentage

For example, here is a picture that I took of Grand place at night through this process:

Original Picture (7.6 MB)

Compressed Picture (761 KB)

Compressed Picture (241 KB)

Compressing Video#

To compress a video, you can use an Online compressor like Freeconvert. Nothing complicated!