2. Project management

The topic of this week is project management. We learned many kinds of tools for version control, documatations, file sharing, remote communication and so on.

Assignment

Git Tutorial

As following tutorial page, I set up my git for fabcloud.

I have already setup my own account on the GitHub for sharing some codes in public. Moreover, I have also setup my own GitLab Page for using some of my research projects. Therefore, in this assignment, I set up my git to pull/push to my repository in the fabcloud.

Confirm whether Git has already installed.

I used Mac OS Mojave. So, first, I open the Terminal and type ‘git’ command. The result shows the explanation of git command, and I confirmed git is installed in my Mac.

$ git
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone      Clone a repository into a new directory
   init       Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add        Add file contents to the index
   mv         Move or rename a file, a directory, or a symlink
   reset      Reset current HEAD to the specified state
   rm         Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect     Use binary search to find the commit that introduced a bug
   grep       Print lines matching a pattern
   log        Show commit logs
   show       Show various types of objects
   status     Show the working tree status

grow, mark and tweak your common history
   branch     List, create, or delete branches
   checkout   Switch branches or restore working tree files
   commit     Record changes to the repository
   diff       Show changes between commits, commit and working tree, etc
   merge      Join two or more development histories together
   rebase     Reapply commits on top of another base tip
   tag        Create, list, delete or verify a tag object signed with GPG

collaborate (see also: git help workflows)
   fetch      Download objects and refs from another repository
   pull       Fetch from and integrate with another repository or a local branch
   push       Update remote refs along with associated objects

'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
YosukenoMacBook-puro-7:~ yosuke$

Configure Git username and email

Next, I added my git username and email. Then I checked the file of .gitconfig and I confirmed username and email address was addeed to configurations of git.

$ git config --global user.name "tsuchiya.yosuke"
$ git config --global user.email "t24333@aoyamagakuin.jp"
$ more .gitconfig 
[filter "lfs"]
        clean = git-lfs clean -- %f
        smudge = git-lfs smudge -- %f
        process = git-lfs filter-process
        required = true
[user]
        name = tsuchiya.yosuke
        email = t24333@aoyamagakuin.jp

Generate SSH key for fabcloud

Next is to generate SSH Key. I have already generated every different SSH key for my own web server, my github accound and my own gitlab. I want to generate different SSH key for my fabcloud account, so I moved to “.ssh” folder and generated SSH key with adding option “-f” for saving keyinfo in different file. 

$ cd .ssh
$ ssh-keygen -t rsa -C "t24333@aoyamagakuin.jp" -f fabcloud.rsa

Checking .ssh folder and I confirmed that public/private key files for fabcloud (fabcloud.rsa/fabcloud.rsa.pub) are generated.

$ ls
backup_ssh      fabcloud.rsa        github_rsa.pub      id_rsa          known_hosts~
config          fabcloud.rsa.pub    gl.ysklab.net_rsa   id_rsa.pub      ysk-aws.pem
config~         github_rsa      gl.ysklab.net_rsa.pub   known_hosts

However, in this case, when connecting to fabcloud, git cannot specify which key should be used. So, I added Host, user and identityFile info to the config of ssh (.ssh/config) as follow. 

AddKeysToAgent yes
UseKeychain yes

Host gl.ysklab.net
     User git
     identityFile ~/.ssh/gl.ysklab.net_rsa

Host gitlab.fabcloud.org
     User git
     identityFile ~/.ssh/fabcloud.rsa

Then, I copied my SSH public key to the fabcloud.

I show my pulic key info using cat command. Key info starts from “ssh-rsa” phrase and end with e-mail address that I put when the key was generated.

$ cat fabcloud.rsa.pub 
ssh-rsa  ... (sorry, I would like to hide key info itself) ...  t24333@aoyamagakuin.jp

I logged in to the fabcloud, and moved to SSK keys setting page. I pasted public key into the form of key, then pushed “Add key” button. When pasting the key, e-mail address is shown in the title form.

Then, with seeing this screen, I confirmed my key was registered correctly.

Checking Git works well

To check whether git works on my Mac, I tried to clone my fabacademy repository. First, I created a new folder for fabacademy assignments on my home folder with using “mkdir” command. Then I moved to the folder by cd command.

$ mkdir fabacademy
$ cd fabacademy/

At the fabacademy folder, I cloned my fabacademy repository.

$ git clone git@gitlab.fabcloud.org:academany/fabacademy/2019/labs/kamakura/students/tsuchiya-yosuke.git

Cloning into 'tsuchiya-yosuke'...
Enter passphrase for key '/Users/yosuke/.ssh/fabcloud.rsa': 
remote: Counting objects: 171, done.
remote: Compressing objects: 100% (64/64), done.
remote: Total 171 (delta 98), reused 171 (delta 98)
Receiving objects: 100% (171/171), 405.19 KiB | 608.00 KiB/s, done.
Resolving deltas: 100% (98/98), done.

By using “ls” command, I confirmed my repository was successfully cloned into the folder.

$ ls
tsuchiya-yosuke

build a personal site in the class archive

Now, I am get ready to build up my own fabacademy website. Because I want to get used to wirte documents in markdown, I decided to use MkDocs for generating my website.

Install MkDocs on my Mac.

First, with following the installation page, I installed MkDocs on my Mac. Then, to confirm MkDocs works well, I moved to my fabacademy repository, then type “mkdocs serve”. 

$ mkdocs serve
INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
[I 190125 21:04:19 server:298] Serving on http://127.0.0.1:8000
[I 190125 21:04:19 handlers:59] Start watching changes
[I 190125 21:04:19 handlers:61] Start detecting changes

And, I opened the web browser and accessed to “http://127.0.0.1:8000”. I can see mkdocs works welll on my Mac.

Theme Change

Next, I tried to change the site theme. First, I accessed to MkDocs-theme page. I can change the theme of my website by re-writng “theme” section in mkdocs.yml file located in the top of my repository. Most of MkDocs theme can be install by using pip (Pip Install Packages) and pip have already installed when setting up MkDocs on my Mac.

For example, if I want to install windmill theme, 

pip install mkdocs-windmill

Then, I rewrite theme section of mkdocs.yml as following:

theme: windmill

The theme changed to windmill.

Trying all templates that are introduced in the MkDocs-theme page, I dedided to use bootswatch theme. Bootswatch is nice because I can choose some combination of site colors in this theme.

To install bootswatch, I did:

pip install mkdocs-bootswatch

Then, I changed theme section of mkdocs.yml. In my website, I choosed “cosmo” in bootswatch theme.

theme:
  name: cosmo

Other setting and Editor

It looks very nice that MkDocs automatically generate website structure as following directory structure. It is also very nice that all markdown files (.md) have been provided in my repository. However, I don’t want to show links to files of assignments that haven’t finished yet in the navigation bar. Therefore, I customized the navigation bar with re-writing “nav” section in modocs.yml as follow.

nav:
    - Home: index.md
    - About: ./about/index.md
    - Assignments:
      - 1. Principles and Practices: ./assignments/week01.md
      - 2. Project Management: ./assignments/week02.md
    - Final Project: ./projects/final-project.md

Then, I can see navigation bar was changed. I confirmed that only week 1 (Principles and Practices) and week 2 (Project Management) are listed in the assignment menu.

When I start “mkdocs serve”, the following information are displayed. It is because I didn’t write markdown file info of assignments in the “nav” section of mkdocs.yml. 

YosukenoMacBook-puro-7:tsuchiya-yosuke yosuke$ mkdocs serve
INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - assignments/week03.md
  - assignments/week04.md
  - assignments/week05.md
  - assignments/week06.md
  - assignments/week07.md
  - assignments/week08.md
  - assignments/week09.md
  - assignments/week10.md
  - assignments/week11.md
  - assignments/week12.md
  - assignments/week13.md
  - assignments/week14.md
  - assignments/week15.md
  - assignments/week16.md
  - assignments/week17.md
  - assignments/week18.md
  - assignments/week19.md
  - assignments/week20.md
  - projects/sample-project.md  
[I 190125 22:41:12 server:298] Serving on http://127.0.0.1:8000
[I 190125 22:41:12 handlers:59] Start watching changes
[I 190125 22:41:12 handlers:61] Start detecting changes

I use emacs to edit .md files. I open emacs on the Terminal and keep left side, and I show the Web browser (Safari) on the right side. By doing so, I could edit and save the file on emacs, with seeing what looks like on the browser.

Push updated webisite file to my repo.

After finished to edit, I uploaded files to my repository.

First, I added new and updated files to git (add .), and download the last copy from the repository (git pull).

$ git add .
$ git pull
Already up to date.

Then, use “git commit” to add description of update.

$ git commit -m "edited week02 assignment."
[master e3c43fd] edited week02 assignment.
 10 files changed, 305 insertions(+), 75 deletions(-)
 rewrite docs/assignments/week02.md (98%)
 create mode 100644 docs/assignments/week02_img/2-1.jpg
 create mode 100644 docs/assignments/week02_img/2-2.jpg
 create mode 100644 docs/assignments/week02_img/2-3.jpg
 create mode 100644 docs/assignments/week02_img/2-4.jpg
 create mode 100644 docs/assignments/week02_img/2-5.jpg
 create mode 100644 docs/assignments/week02_img/2-6.jpg

Finally, use “git push” to upload to the repository, and wait a few minutes.

$ git push
Counting objects: 15, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (15/15), done.
Writing objects: 100% (15/15), 788.50 KiB | 21.90 MiB/s, done.
Total 15 (delta 4), reused 0 (delta 0)
To gitlab.fabcloud.org:academany/fabacademy/2019/labs/kamakura/students/tsuchiya-yosuke.git
   32ae5c3..e3c43fd  master -> master

Now, I accessed to my fab academy archive page.

describing me and my final project