Skip to content

2. Project management

Assignment

Work through a git tutorial build a personal site in the class archive describing you and your final project

Have you?

  • Made a website and described how you did it
  • Introduced yourself
  • Documented steps for uploading files to archive
  • Pushed to the class archive
  • Signed and uploaded Student Agreement

1. Made a website and described how you did it

The website to be used for fabacademy was given as template and recommended to not to change the used template. The majority of the composite was already given.

Building the website documentation is done by MkDocs through the Gitlab repository.
The website documents are in Markdown markup language and formatting is configured with singe yml -file.

First, configure of the website was using text editing software to edit the changing the site name and site author to my name and updated file to the repository

mkdocs.yml file. The site author and site name edited.

When using the Mkdocs template site the only way to change the composition of the site is through the mcdocs.yml.

In the mcdocs.yml file, most site affecting parameters are the theme, palette and the extra_css. Styling and the layout can be easily modified by changing the line:

name:

in the Theme part to “mkdocs”, “readthedocs” or “material” theme.

Theme part of the mkdocs.yml file

After pushing the file and waiting the 60 minutes the change takes effect the site will be changed to the new layout. After testing the different alternatives I settled to the default material theme. I changed the color scheme to primary color “Red” and the accent color to “Deep Orange”.

CSS formating can be inserted to extra.css file and naming the file in the mcdocks.yal -file.

Extra.css confirugation.

The extra.CSS file takes normal CSS formatting configuration options and they are used to specifically include CSS formatting.

Extra.css confirugation file input formating. This parameter will change the color of the background. Slightly off-white grey was selected because of the wear of the user eyes and it cuts the harshness against the selected color scheme.

The site pages are then edited in Brackets editor that includes proofreading and markdown viewer.


2. Introduced yourself

Introduction is located in about page

3. Documented steps for uploading files to archive.

Fabacademy uses Gitlab as the archive of the course.

Git - The cruel act to create a revision control system which is expressly designed to make you feel less intelligent than you thought you were.

Git was originally designed by Linus Benedict Torvalds In 2 weeks after decided he can write something better than anything out there for CVS version control”

The name git came from Linus himself. -“I’m an egotistical bastard, and I name all my projects after myself. First ‘Linux’, now ‘git’(which means an unpleasant person in British English slang).”

What are Git CMD, Bash and GUI variants:

  1. Git CMD is just like regular Windows command prompt with the git command. It lets you use all of the Git features through the command line. Useful if you are already familiar with Windows cmd and you only work on Windows.

  2. Git Bash emulates a bash environment on windows. It lets you use all git features in command line plus most of the standard UNIX commands. Useful if you are used to Linux and want to keep the same habits.

  3. Git GUI is a Graphical User Interface letting you use Git without touching the command line. It is an alternative among other Git clients.

Otherwords: Same but different.

Starting using the Git.

First, the git.com program was installed to the computer from the https://git-scm.com/

Git CMD and Git Bash command line was used to use Git.

After installation GitCMD was configured to recognize email with the command: 

git config -–global user.email “perttu.piirainen@buutti.com”

This gives git information about the user.

In order to use Git, a public SSH key pair needs to be generated. Secure Shell (SSH) is a cryptographic network protocol for operating network services securely over an unsecured network. Typical applications include remote command-line login and remote command execution, but any network service can be secured with SSH. SSH provides a secure channel over an unsecured network in a client-server architecture, connecting an SSH client application with an SSH server. SSH uses public-key cryptography to authenticate the remote computer and allow it to authenticate the user, if necessary. There are several ways to use SSH; one is to use automatically generated public-private key pairs to simply encrypt a network connection and then use password authentication to log on. On a Git both methods can be used.

  • The GitBash was used to create SSH key to the repositiry. The command ” ssh -t rsa -C “perttu.piirainen@buutti.com” -b 4096”. .

    This generates 4096 bit long RSA-algorithm key. Bash then asks for a password to secure the key file.


  • The public key is stored to the computer. The public was copied from the id_rsa-pub file it was created.


  • The pubkey was copied to gitlab using insturctions In the Gitlab site in the preferencies the SSH keys has the place where key is copied.


  • The SSH git address was copied from repository page:

    SSH gitlab address

  • The SSH git address was copied to the Git Bash with the command “git clone git@gitlab.fabcloud.org:academany/fabacademy/2019/labs/oulu/students/perttu-piirainen.git” this copies the git filestructure to the used computer.

4. Add, Commit, Push, Pull and Status

  • Local repository consists of three directory trees. Working directory, index, and HEAD.

  • Any work done is first saved to the working directory. If anything is wanted to propose changes they are added to the index by “git add *” command. The index is a single, large, binary file which lists all files in the current branch, their sha1 checksums, timestamps, and the file name – it is not another directory with a copy of files in it. After add command, the files are tracked by the stage.

  • Commit takes the files as they are in the staging area and stores that snapshot permanently to local Git directory. If any changes need to be done they need to be added again to the stage area.

  • Push uploads the changes in files to the external repository.

  • Pull is used to make the local working directory up to date to latest files on the remote git repository.

  • Status command displays the state of the working directory and the staging area. It lets you see which changes have been staged, which haven’t, and which files aren’t being tracked by Git.

5. Pushing to the class archive

The Mkdocs.yml was edited to change the default page appearance and saved to the local computer.


The changes to the files were first added by giving the command:

git add --all

The addition is then moved to the staging area by:

git commit -m "Enter your comment here"

The final upload is done by push:

git push --all

to the commit and pushed to the repository.


7. Signed and uploaded Student Agreement

The student agreement was copypasted from the assignment page to a newly created file in the About page

8. Some observations Aka. the problems:

  1. The Table of the contest has vanished from this page. Haven’t really figured out why. Things I have tried in desperate to revive the TOC: Tried to observe the .md file page code for missing code snipped without any success.
    Opened the *.md file with a hex editor and CheatEngine to see if file consists some kind of header or footer without any success.
    Rolled back to the first version of the file without any success.
    Copied another student week02.md and replaced my file whit it without any success
    Removed and replaced the week02.md file entirely without any success.
    I might have an idea: the order of the headlines indentation may break the TOC. SOLVED: Either using the fourth level headline anywhere or using the first level headline anywhere else than on the first line, the table of content will disappear. Was this behavior documented anywhere? I cannot find anything to describe this.

  2. I have been using Git and its variations for file version control for years. All of my problems are related to the inconsistency of Markdown code translate to the page.

  3. The extra.css seems to be one-time use file. modifying a yml file to use a *CSS file updates the edits to the page. If the same extra.scc file is used again it does not modify the page. One workaround is to make extra+n.scc file and edit the corresponding yam file to add the extra+n.scc name modification the same time. Further edits to extra+n.css needs the creation of a new extra+n+1.css file and edit to yml file to include the newest extra+n+1.scc. This way the new CSS edits will go through.

4.HTML code works randomly. for example 

<img src=".jpg" alt="picture">

code will work sometimes, and on other, it will only print the code line as is. Some HMTL codes do work. Haven’t found really a good list of what everything works. Everything is a trial error at this point.

5.Changing the styling will reset every .css modifications. This means that the extra.scc configurations will not be moved to the new theme. The new theme will be reset to default formatting. Every new formatting will need a new extra+n.scc and yml file pair.

6.The commint pipeline time will go up exponentially if multiple change request are done simultaneously.

Sometimes wait time to commit to run until “Commit passed” takes a long time.

This behaves weirdly. There is a Pending- time before the commit goes to working the commit. The pending time is not accounted to the commit work time and is not shown in the logs. After the commit has gone to passed mode does not mean that the markdown page updates. The page to finally to be shown can take anything from minutes to hours.

7.Using Termux ( Alinux command line emulator for Android) to git has some interesting side effects. Mainly git does not like the unstable 3G connection while pushing the changes from a mobile phone while bicycling.

8.Somehow using 

<center><img src="../../images/week*/*.jpg"></center><caption> <center></center></caption><br>

As image tag shows the image in the Markdown preview in Notepad++ MarkdownViever++ and in the WebIDE viewer in the Gitlab website, but refuses to show the image in the uploaded fabacademy page itself. I can copy-paste a working html image tag to another weeks page, and not change anything, and it shows up as error. Copy-pasteing the same tag to another week page and it works again… I have no idea why or how. The markdown formatting:

![](../../images/week02/kuva1%20bitbashbasic.jpg"></center><caption> <center></center></caption><br>

Does not work every time.But enough reliably. So I will be using that method to show any in repository pictures.

Edit from the future:

This behavior is random and inconsistent. Sometimes “../../images” linking works. Other times only an error is displayed.
Also: does the pipeline commit time count the “pending” time? In the jobs page, the displayed work time does not represent the real-life waiting time. The pipeline wait time varies heavily for unknown reasons. Maybe a server-side load is at times higher.

Reflection

There are some quirks in the usage of this page. Most of them are very undocumented. Time spend to make this page 146h out of advertised 20h/week Edit: 150h

I will try to solve these problem later. As of rifht now, the Final project is the main focus.