Skip to content

2. Project management

2.1 Version control protocols

2.1.1 What is version control

“Document version control is the process of tracking and managing different versions (or drafts) of a document, so you know which is the current iteration of a file.” ~ Elizabeth Harrin

The process of version control is a fundamental concept and skill as it allows to keep an audit trail of how a file has been changed, when and by whom.

2.1.2 Basic steps for version control

The analog procedure is the creation of a table in the front of the document/file in question to keep record of the following:

  • version number

  • date

  • author

  • rationale — a brief summary of changes in that iteration of the document

In the case of digital versions being saved, file names are changed as the process develops.

2.1.2.1 Version control numbering

Each draft of the document is saved as an incremental number: 0.1, 0.2, 0.3, etc — until the point in which the document is approved.

Subsequent edited versions become 1.1, 1.2, 1.3, etc. The ‘.x’ part of the number denotes a small change made. In the case of major changes or updates, the document is renamed a whole number (e.g 2.0. 3.0, 4.0, etc)

2.1.2.2 Rationale

The rationale is the brief description highlighting the difference between the new version in comparison to the last one. At times the version number might be the only change taking place; specifically in cases when the current version becomes the final one until the next update. A couple of words reflecting the procedure taking place in the file to allow others to quickly spot the differences.

2.2. Website development tools

The creation a Git repository, (a version controlled system [git-scm]), is to be used during Fab Academy for effective work documentation and the successful addition of files.

The Git repository will be hosted on the Fab Academy Git lab. By having it as local installation, it will allow us to make changes and have them published/’pushed’ as needed.

2.2.1 Git Workshop

Procedure for the creation of a Git repository The first thing is to clone the project in order to put it on my hard drive

type in terminal:
ssh git@gitlab.fabcloud.org

Once the message was positive, I went to Git and clicked ‘clone’.

From the dropdown menu, I selected ‘copy’ and took it to the terminal to paste it into the targeted folder. In this case, it was meant to go to the ‘Desktop’.

Once a positive message had been received, I went to Git and clicked “Clone”. On the “drop down menu” I selected ‘copy’ and took it to the terminal in order to add it to the ‘Desktop’.

Ximenas-MacBook-Pro:~ ximenaamador$ cd Desktop
Ximenas-MacBook-Pro:Desktop ximenaamador$ git clone git@gitlab.fabcloud.org:ximena.amador/understanding-git.git
Cloning into 'understanding-git'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.

Went inside the repository to find the right folder and opened a document.

Once at the right folder, opened a document.

In order to open a repository on my screen I typed: open .

Ximenas-MacBook-Pro:understanding-git ximenaamador$ open .

To open a file I used: 

Ximenas-MacBook-Pro:understanding-git ximenaamador$ echo Hello > myfile.txt
Ximenas-MacBook-Pro:understanding-git ximenaamador$ ls

TIP: Tab is used as autocomplete

“git add ” is to add a git repo
“git add .” add all the content of a directory
“git status”

TIP: Tab is used as autocomplete :)

First attempt at adding [gone wrong]

Ximenas-MacBook-Pro:myfolder ximenaamador$ git add
Nothing specified, nothing added.
hint: Maybe you wanted to say 'git add .'?
hint: Turn this message off by running
hint: "git config advice.addEmptyPathspec false"
Ximenas-MacBook-Pro:myfolder ximenaamador$ git diff
Ximenas-MacBook-Pro:myfolder ximenaamador$ git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:

(use "git add <file>..." to include in what will be committed)
../.DS_Store
./
../test-repo/

Nothing added to commit but untracked files present (use “git add” to track)

Ximenas-MacBook-Pro:myfolder ximenaamador$ git log
commit f28a182f86a8a6bef4cd37215411a8c0ee0e2566 (HEAD -> main, origin/main, origin/HEAD)
Author: Ximena Amador Peña <ximenaamador@yahoo.com>
Date:   Mon Apr 25 13:15:33 2022 +0000

Initial commit

Ximenas-MacBook-Pro:myfolder ximenaamador$

The message to add is the ‘why’ behind each commit, fundamental for version control

TIP: ‘ESCAPE’ to get out of insert mode (where you can’t write)

Commit message: git commit -m “ASDASDA”

TIP: An alternative key combination for a commit is Control + K

Ximenas-MacBook-Pro:myfolder ximenaamador$ git log
commit 6d2b9a81142f68c3951709fbed0933f382c75660 (HEAD -> main)
Author: ximena.amador <ximenaamador@******.com>
Date:   Mon Apr 25 16:08:48 2022 +0200

ASDASDA

commit f28a182f86a8a6bef4cd37215411a8c0ee0e2566 (origin/main, origin/HEAD)
Author: Ximena Amador Peña <ximenaamador@******.com>
Date:   Mon Apr 25 13:15:33 2022 +0000

2.2.2 mkdocs setup

The Fab Academy documentation is to be formatted using Markdown.

MkDocs must be installed locally in order to generate a static website as well as to validate all content before it being ‘pushed’ and made public.

mkdocs Figure 1. mkdocs.yml page after installation

Website Figure 2. ‘About me’ section on website

2.3 Final Project Ideas

Initial ideas and sketches of my Final Project can be found here.

2.4 Student Agreement

My Student Agreement can be found here.

Last update: October 6, 2023