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.
- work through a git tutorial
- build a personal site in the class archive describing you and your final project
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 "firstname.lastname@example.org" $ 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 = email@example.com
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 "firstname.lastname@example.org" -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) ... email@example.com
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 firstname.lastname@example.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.
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:
The theme changed to windmill.
To install bootswatch, I did:
pip install mkdocs-bootswatch
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.