Skip to content
Snippets Groups Projects
Principles and Practices + Project Management.md 13.9 KiB
Newer Older
Mitalee Parikh's avatar
Mitalee Parikh committed
#Principles, Practices and Project Management
Mitalee Parikh's avatar
Mitalee Parikh committed
This week I learned about version control, web development using SSGs, and sketched out some ideas for my final project.
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
### Page Summary
1. Version control
2. Git and GitLab
Mitalee Parikh's avatar
Mitalee Parikh committed
3. Setting up Git for FabAcademy documentation + SSH keys
4. Basic workflow and repository structure + Working through a Git Tutorial
Mitalee Parikh's avatar
Mitalee Parikh committed
5. About CI/CD
6. Web Development with Static Site Generators
7. YAML file
8. Web Design
9. Misc upload practices
10. Important and Interesting Links
11. Initial Final Project Ideas
12. About page
Mitalee Parikh's avatar
Mitalee Parikh committed
---
Mitalee Parikh's avatar
Mitalee Parikh committed

1. Version Control
Mitalee Parikh's avatar
Mitalee Parikh committed
---
Mitalee Parikh's avatar
Mitalee Parikh committed
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.  
Mitalee Parikh's avatar
Mitalee Parikh committed
Ref: [What is version control](https://www.atlassian.com/git/tutorials/what-is-version-control)
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
2. Git and GitLab
Mitalee Parikh's avatar
Mitalee Parikh committed
---
Mitalee Parikh's avatar
Mitalee Parikh committed
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.
Mitalee Parikh's avatar
Mitalee Parikh committed
FabAcademy uses a self-hosted version of GitLab on FabCloud at [gitlab.fabcloud.org](gitlab.fabcloud.org), which is where all projects related to the academies and student documentation websites are hosted.  
Mitalee Parikh's avatar
Mitalee Parikh committed
Ref: [Git](https://git-scm.com/about)
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
3. Setting up Git for FabAcademy documentation
---
Mitalee Parikh's avatar
Mitalee Parikh committed
On Fabcloud our individual repositories are housed under *Academany > FabAcademy > Year > List of Labs > Lab > Students > Name*  

Mitalee Parikh's avatar
Mitalee Parikh committed
One way to log on to Fabcloud is use login credentials from [fablabs.io](https://fablabs.io/). It is the same login credentials used used for other FabAcademy communication - like [Nueval](https://nueval.fabacademy.org/#/) for assessment and the [Network](live.fablabs.io).
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
1. Install Git on local computer.  
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
    To install Git through the command line - Terminal app (macOS), first install [Homebrew](https://brew.sh/), a package manager using the instructions on the website.  
Mitalee Parikh's avatar
Mitalee Parikh committed
    ![](./images/pppm/brew.png)  
    and then   
    `brew install git`  
    There are other ways to install git as mentioned on the website too.  
Mitalee Parikh's avatar
Mitalee Parikh committed
    Ref: [git-scm](https://git-scm.com/download/mac)  
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
2. Configure user  
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
    To configure a user from scratch, in terminal, add a Git username and set an email for uploading. In my case it is:    
Mitalee Parikh's avatar
Mitalee Parikh committed
    `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.  
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
3. Generate SSH key  
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
    Check if an SSH KEY already configured  
Mitalee Parikh's avatar
Mitalee Parikh committed
    `cat ~/.ssh/id_rsa.pub`  
    If not, generate it using  
    `ssh-keygen -t rsa -C "emaitee@gmail.com"`  
Mitalee Parikh's avatar
Mitalee Parikh committed
    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.  
Mitalee Parikh's avatar
Mitalee Parikh committed

4. Start a git repository  
Mitalee Parikh's avatar
Mitalee Parikh committed

    There are several ways to make a repository:  
    1. On the GitLab website, create a repository and then clone it locally.  
    2. In the terminal initialising it from scratch using `git init` by changing current directory to desired location.  
    3. Cloning an existing one.  
Mitalee Parikh's avatar
Mitalee Parikh committed
    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.  
Mitalee Parikh's avatar
Mitalee Parikh committed
    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.  
Mitalee Parikh's avatar
Mitalee Parikh committed
    ```
Mitalee Parikh's avatar
Mitalee Parikh committed
    `git clone git@gitlab.fabcloud.org:academany/fabacademy/2020/labs/barcelona/students/mitalee-parikh.git`  
Mitalee Parikh's avatar
Mitalee Parikh committed
    ```
    Now, a clone of the template is made on the local repository.  
Mitalee Parikh's avatar
Mitalee Parikh committed
    ![](./images/pppm/clone.png)  
Mitalee Parikh's avatar
Mitalee Parikh committed

4. Basic workflow and repository structure  
Mitalee Parikh's avatar
Mitalee Parikh committed
---
Mitalee Parikh's avatar
Mitalee Parikh committed
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  
Mitalee Parikh's avatar
Mitalee Parikh committed
`git add .` to add all changes from the working directory to the staging area  
Mitalee Parikh's avatar
Mitalee Parikh committed
`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  
Mitalee Parikh's avatar
Mitalee Parikh committed
I find this diagram very helpful to visualise the directory structure:  
Mitalee Parikh's avatar
Mitalee Parikh committed
![](./images/pppm/staging.png)  
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
My first commit from git log  
![](./images/pppm/initialcommit.png)  
Mitalee Parikh's avatar
Mitalee Parikh committed
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  
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
It is easier to undo a staged file, i.e. after git add  
Mitalee Parikh's avatar
Mitalee Parikh committed
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.  
Mitalee Parikh's avatar
Mitalee Parikh committed
Check this guide in case I need to undo anything.  
Mitalee Parikh's avatar
Mitalee Parikh committed
Ref: [How to undo (almost) anything with Git](https://github.blog/2015-06-08-how-to-undo-almost-anything-with-git/)  
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
5. About CI/CD
---
Mitalee Parikh's avatar
Mitalee Parikh committed
Continuous Integration compiles websites with static site generators.  
Mitalee Parikh's avatar
Mitalee Parikh committed
Ref: [docs.gitlab.com/ee/ci/](https://docs.gitlab.com/ee/ci/)  
Here is a guide to understand how and why *commit > build > test > stage > deploy* works so effciently.
Mitalee Parikh's avatar
Mitalee Parikh committed
Ref: [CI/CD Explained in 100 Seconds](https://www.youtube.com/watch?v=scEDHsr3APg)  
Mitalee Parikh's avatar
Mitalee Parikh committed
How it works...   
You create a gitlab-ci.yml file (HTML).   
Then a "runner" server picks up your "Pipeline"   
Reading your .gitlab-ci.yml file will execute your scripts in Docker.   
After completing your steps in the .yml file, GitLab stores the results and publishes them on the web.   

6. YAML file
Mitalee Parikh's avatar
Mitalee Parikh committed
---
Mitalee Parikh's avatar
Mitalee Parikh committed
First git reads the YAML file .gitlab-ci.yml in the repo.  
Mitalee Parikh's avatar
Mitalee Parikh committed
GitLab has a list of example repositories for common static static site generators or HTML at [gitlab.com/pages](https://gitlab.com/pages).  
Understanding the default Mkdocs-CI YAML file in the repo  
Mitalee Parikh's avatar
Mitalee Parikh committed
![](./images/pppm/yml.png)  
```
# What type of container should run this job (where the script will run)
image: python:3.8-slim
# This is the "job" name
pages:
  # This tells GitLab which group the "job" belongs
  stage: deploy
  # Set any environment variables to be available inside the container
  variables:
    GIT_DEPTH: 1000
  # These are the commands that will run in the job
  script:
      # This is a specific mkDocs command to make the HTML
      - time mkdocs build --site-dir public
  # Tells GitLab which folder to copy out of the "job" to send to another "job"
  artifacts:
    paths:
    # Select the public folder in this case, so it can be sent to GitLab Pages
    - public
  only:
      - master
```

7. Web Development with SSGs
Mitalee Parikh's avatar
Mitalee Parikh committed
---
Mitalee Parikh's avatar
Mitalee Parikh committed
The basic way to make a website is using HTML code for content, and maybe using CSS and javascript for styling.  
Mitalee Parikh's avatar
Mitalee Parikh committed
Another efficient way to make websites is to use static site generators.   
Mitalee Parikh's avatar
Mitalee Parikh committed
To develop my webpage, I use the existing Mkdocs to first understand how it works. Jekyll is another option I want to use to make a custom themes maybe later on.  
Mitalee Parikh's avatar
Mitalee Parikh committed
There are many options of Static Site generators like [Hugo](https://gohugo.io/), [Jekyll](https://jekyllrb.com/), [Gitbook](https://www.gitbook.com/)[docs](https://docs.gitbook.com/), [Mkdocs](https://www.mkdocs.org/), [Middleman](https://middlemanapp.com/), etc. each with their own special features for the kind of website one wants to make.
Mitalee Parikh's avatar
Mitalee Parikh committed
This GitLab page has a list of example repositories for common static static site generators or HTML at [gitlab.com/pages](https://gitlab.com/pages).  
The basic way to start is clone one of these, unattach and start modifying.  

### Setting up Mkdocs
Intalling and upgrading package manager pip `pip install --upgrade pip` to install mkdocs: `pip install mkdocs`  
To view the changes on my local server `http://127.0.0.1:8000` I used `mkdocs serve`  
Ref: [Markdown](https://en.wikipedia.org/wiki/Markdown) [basic tutorial](https://www.markdowntutorial.com/)  
[Mkdocs guidelines](https://www.mkdocs.org/) has all instructions to customise the website.  

### Setting up jekyll  
I followed this [Jekyll tutorial](https://jekyll.org) by [Giraffe Academy](https://www.youtube.com///playlist?list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB). Before installing jekyll, I checked if I had these supporting things, and updated them:  
1\. **Homebrew:** to easily install software packages  
2\. **Ruby:** programming language that jekyll is written in  
3\. **RubyGems:** package manager for ruby  
4\. **Bundler:** to track and install gems and versions in a group, for jekyll themes  
Homebrew, Ruby and Gem were all pre-installed.  
So I checked versions using  
`ruby -v` and `gem -v`  
I installed bundler with `gem install jekyll bundler`, but got a permissions error msg.  
So, I tried it with sudo like so: `sudo gem install jekyll bundler` and it worked.  
And then to make sure checked version: `gem install jekyll bundler`
To view the changes on my local server `http://localhost:4000` I used `bundle exec jekyll serve` the first time and
Jekyll serve everytime after.
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
8. Web Design
Mitalee Parikh's avatar
Mitalee Parikh committed
---
Mitalee Parikh's avatar
Mitalee Parikh committed
I wanted my website to be as simple as possible from features, animations, colours, etc. So that the content is not overpowered by any distractions. I used the [MKdocs material theme document guide](https://squidfunk.github.io/mkdocs-material/getting-started/) to change colours, fonts, etc.  
Mitalee Parikh's avatar
Mitalee Parikh committed

Mitalee Parikh's avatar
Mitalee Parikh committed
I did a quick exercise to define some aspects for the web design:  
![](./images/pppm/site.png)  
Mitalee Parikh's avatar
Mitalee Parikh committed

9. Misc Practices
Mitalee Parikh's avatar
Mitalee Parikh committed
---
Mitalee Parikh's avatar
Mitalee Parikh committed
There is a 10Mb limit per commit for FabAcademy documentation, so all big images, videos (if not hosted) need to be compressed into smaller sizes.
`du -sh * ` to check file sizes
`du -sh * | sort -n ` sorts the files by size

Mitalee Parikh's avatar
Mitalee Parikh committed
Before pushing, I used `ncdu` to check sizes of files. To compress my images I installed and used [ImageMagick](https://imagemagick.org/index.php). I found it very efficient to quickly convert or compress images for the web, and also to make quick GIFs.
Mitalee Parikh's avatar
Mitalee Parikh committed
After some trial and error, i figureed these basic commands and settings I can use for my workflow:  
Mitalee Parikh's avatar
Mitalee Parikh committed
To compress photos taken from my phone:  
Mitalee Parikh's avatar
Mitalee Parikh committed
`convert IMGname.HEIC -resize 25% -quality 50% -density 72 jpg:extent=300kb IMGnewname.jpg`  
Mitalee Parikh's avatar
Mitalee Parikh committed
To compress images taken as screenshot from my computer:  
Mitalee Parikh's avatar
Mitalee Parikh committed
`convert Screenshot.png -resize 50% -quality 50% -density 72 jpg:extent=300kb newname.jpg`  
Mitalee Parikh's avatar
Mitalee Parikh committed
To make a quick GIF:  
Mitalee Parikh's avatar
Mitalee Parikh committed
`convert -resize 25% -delay 15 -loop 0 IMG_1380.HEIC IMG_1381.HEIC IMG_1382.HEIC IMG_1386.HEIC IMG_1387.HEIC IMG_1388.HEIC   animation.gif`  
Mitalee Parikh's avatar
Mitalee Parikh committed
And to check the existing properties of an image:  
Mitalee Parikh's avatar
Mitalee Parikh committed
`magick identify -verbose focus.gif`  
I also check individual file sizes by changing current directory in terminal and using `du -sh *|sort -n`  
Mitalee Parikh's avatar
Mitalee Parikh committed
10. Important and interesting links
Mitalee Parikh's avatar
Mitalee Parikh committed
---
Mitalee Parikh's avatar
Mitalee Parikh committed
[Principles and Practices notes](http://academy.cba.mit.edu/classes/principles_practices/index.html) + [video](https://vimeo.com/505368120)  
[Project Management notes](http://academy.cba.mit.edu/classes/project_management/index.html) + [video](https://vimeo.com/505364047)  
[Everything is a file](https://en.wikipedia.org/wiki/Everything_is_a_file)  
[Linus kernel development video]()  
[The Bash Guide](https://guide.bash.academy/)  
[FabLabBCN local documentation guides](https://fablabbcn-projects.gitlab.io/learning/fabacademy-local-docs/guides/code/gitsetup/)  
Mitalee Parikh's avatar
Mitalee Parikh committed

11. Initial Final Project Ideas
---
Mitalee Parikh's avatar
Mitalee Parikh committed
### Idea 1: Light source

For my final project, I want to make a versatile lamp.
A light source that can keep resultant light on a surface constant irrespective of external daylight.

Also, to add some mechanics and automation, make the form versatile to change it from being indirect light, ambient and a task light whenever required.  
* CAD - make 2D for cutting/production  files & make a 3D model, animate and render  
* Inputs - light sensors to measure light color (add light intensity later)  
* Output - Multicolor LED to change output to match resultant light  
* CAM - lasercut parts, use vinyl cutter for origami folds  
* 3D printing - joints, make casing for PCB  
* Electronic design, production and embedded programming - To make the micro-contoller PCB  
* Network and Communication - Add WiFi module to control it remotely  
* Interface and Application programming - To make a GUI (phone app?)  

Mitalee Parikh's avatar
Mitalee Parikh committed
![](./images/pppm/lamp.jpg)  
Mitalee Parikh's avatar
Mitalee Parikh committed

References for the origami form: [Meduse Lamp](http://sdipl.net/slimsSRL/LoadSRLReport.aspx?CID=2110088069&UMR_NO=177803294956&HV=True)  
For the light app: [Philips Hue](http://sdipl.net/slimsSRL/LoadSRLReport.aspx?CID=2110088069&UMR_NO=177803294956&HV=True)  
[Bang & Olufsen](https://apps.apple.com/us/app/bang-olufsen/id1203736217)  

### Idea 2: Modular Robotic Cube

Another idea is to make robotic cubes, that can be assembled by programming themselves. Some references and ides supporing this idea:
![](./images/pppm/references.jpg)
![](./images/pppm/mblocks.jpg) ![](./images/pppm/cubelets.jpg) ![](./images/pppm/cubli.jpg)

I would also like to use the simplicity and [modularity structure](./images/pppm/brochure.pdf) of [MTM](https://mtm.cba.mit.edu/) but in respect to robotics.
![](./images/pppm/mtm.jpg)

### Idea 3: ...  
Mitalee Parikh's avatar
Mitalee Parikh committed
![](./images/pppm/idea3.jpg)  


Mitalee Parikh's avatar
Mitalee Parikh committed
12. About Page
---
Mitalee Parikh's avatar
Mitalee Parikh committed
You can find it through the [homepage](http://academany.fabcloud.io/fabacademy/2020/labs/barcelona/students/mitalee-parikh/) or [this link](http://academany.fabcloud.io/fabacademy/2020/labs/barcelona/students/mitalee-parikh/About%20Me/).