Principles and Practices + Project Management.md



#Principles, Practices and Project Management
This week I learned about version control, web development using SSGs, and sketched out some ideas for my final project.

Page Summary

Version control
Git and GitLab
Setting up Git for FabAcademy documentation + SSH keys
Basic workflow and repository structure + Working through a Git Tutorial
About CI/CD
Web Development with Static Site Generators
YAML file
Web Design
Misc upload practices
Important and Interesting Links
Initial Final Project Ideas
About page


Version Control


Version control, is the practice of tracking and managing changes to software code.

Version control systems are software tools that help teams manage changes to source code over time.

Ref: What is version control

Git and GitLab


Git is an open source distributed version control system.
GitLab is a web-based Git repository for faster and more efficient collaboration of software code.
FabAcademy uses a self-hosted version of GitLab on FabCloud at gitlab.fabcloud.org, which is where all projects related to the academies and student documentation websites are hosted.

Ref: Git

Setting up Git for FabAcademy documentation


On Fabcloud our individual repositories are housed under Academany > FabAcademy > Year > List of Labs > Lab > Students > Name
One way to log on to Fabcloud is use login credentials from fablabs.io. It is the same login credentials used used for other FabAcademy communication - like Nueval for assessment and the Network.


Install Git on local computer.
To install Git through the command line - Terminal app (macOS), first install Homebrew, a package manager using the instructions on the website.


and then

brew install git

There are other ways to install git as mentioned on the website too.

Ref: git-scm


Configure user
To configure a user from scratch, in terminal, add a Git username and set an email for uploading. In my case it is:

git config --global user.name "mitalee.parikh"

git config --global user.email "emaitee@gmail.com"

This helps in tracking who makes the changes on the shared gitlab repo which is public.


Generate SSH key
Check if an SSH KEY already configured

cat ~/.ssh/id_rsa.pub

If not, generate it using

ssh-keygen -t rsa -C "emaitee@gmail.com"

Then use the above command again to view the public key and copy it:

cat ~/.ssh/id_rsa.pub

Upload this key on the Gitlab Website on the browser. It usually begins with 'ssh-ed25519' or 'ssh-rsa'. Go to user profile > Settings > SSH keys and copy it there.

Now, the Gitlab server is securely linked to the local computer.


Start a git repository
There are several ways to make a repository:

On the GitLab website, create a repository and then clone it locally.
In the terminal initialising it from scratch using git init by changing current directory to desired location.
Cloning an existing one.

Since our student repos on GitLab already have a default template installed, we can directly clone it on our local computer, wherever you want to store your documentation.

Your student repo consists of the default student template. First task is to clone this existing template to your local repo. After you cd to your local repo, use this to clone.


`git clone git@gitlab.fabcloud.org:academany/fabacademy/2020/labs/barcelona/students/mitalee-parikh.git`  


Now, a clone of the template is made on the local repository.


Basic workflow and repository structure


The most routine workflow for git : status-(pull)-add-commit-push

git status to check what's happening with the current directory, check if the local and remote repos are synced or need to be updated

git pull to pull files from the remote repo to the local repo, very important if multiple people are pushing to the repo

git add . to add all changes from the working directory to the staging area

git commit -m "action msg" to commit changes from the staging area to the local .git repo, adding a message helps identify and keep a track of the changes made in that particular commit

git push to push only the changes from the local .git repo to Gitlab cloud repo

I find this diagram very helpful to visualise the directory structure:


My first commit from git log


Some other commands that might help:

git clone Clone a repository into a new current local directory, to do once at the beginning of documentation

git init Create an empty Git repository or re-initialize an existing one (starts a .git folder on local computer where all changes will be saved)

git help for help with git commands

Git had very detailed error msgs, so it is advisable to read and follow them to find solutions with issues.

git diff Show changes between commits, commit and working tree, etc

git log Show commit logs
It is easier to undo a staged file, i.e. after git add

but more difficult to undo a committed file, after git commit, but still possible using
git reset --soft HEAD~1 first and then use git restore --staged <file>... to unstage.

Check this guide in case I need to undo anything.

Ref: How to undo (almost) anything with Git