1.5 Project Management¶

Weekly Assignment:¶

Read, sign the student/instructor/lab agreements, and commit to your repos
Work through a git tutorial
Build a personal site in the class archive describing you and your final project

This week I was introduced to GitLab, Markdown, and the documentation process for this website.

Note: The entire process below was performed using Mac OS

Setup¶

Dr. David Taylor gave our lab an introductory presentation to Git and the site setup. I took some notes on what he taught us.

Version Control:

Used for tracking and managing changes to software code by making backups
Creates a history of every change, a timeline you can view
You can experiment by working on it in a silo separately or have multiple people on it in a “merge request”
There are two systems: centralized, the one people send things to, and distributed, which is all centralized

Git:

An open source version control system
Small and fast, saving a snapshot
All distributed, so everyone has it on their + lots of backups
Data integrity, nothing lost
Open source, anyone contribute

There are some other version control systems, like CVS (Concurrent Versions System), SVN (Apache Subversion), and Mercurial (Hg). However, Git is the version control system I used because it is the industry standard and I thought the distributed system would also be very beneficial. I was told that Git's branching model is much more powerful than previous models and able to support fast commits, branching, and merging.

Locations:

Local Repository: on your machine, where you make changes and commit them
Remote Repository: on a server (like GitHub or GitLab) where your project is stored and can be shared with others

Development Environments:

Web Browser: add modifications in the code without having to follow an extensive training in comp sci. Bad bc when you push, there's going to be a lack of syncing and it crashes
Desktop Git Development: On your own computer, allows you to save time bc you will have a copy

Nueval: shows local, global, and progress

Important Terms:

Repo = Repository
Branch: parallel version of your repo
README: a profile README is an “About me”
Commit: set of changes to the files and folders in your project, exists in a branch
Pull request: collaboration happens on it, shows changes in your branch to other people
Merge: adds the changes in your pull request and branch into the main branch

After discussing with Dr. Taylor, I decided I wanted to work on documentation through MkDocs. While I expected some initial setup challenges, I thought it would make the overall long-term process easier for me, making it a worthwhile choice.

The main resources I used to set up GitLab, VS Code, and MkDocs for my project was from Dr. Taylor's GitLab & Nueval Presentation. The generalized process of my work is based off of the AI Workflow Examples, which I found to be immensely helpful.

Note: I had Terminal already downloaded, so I used it as my command-line interface as opposed to PowerShell or Command Prompt.

Homebrew¶

To intall Git, I needed to do it through Homebrew, whose site told me to paste this into Terminal:

/bin/bash -c "$(curl -fsSL

I followed the subsequent instructions until Homebrew was installed, after which I was asked to run three more commands to add it to my PATH.

echo >> /Users/kathrynwu/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/kathrynwu/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

I copied each line into Terminal, but I was not sure if Homebrew had been added to my PATH. So, I consulted ChatGPT, who suggested I try

brew doctor

and let me know that if Terminal responded with

Your system is ready to brew.

that would be an indication of everything having been set up properly.

Note & Tip: A lot of my troubleshooting and general advice was also derived from ChatGPT. This is a public link to my chat history where you can access my prompts and Chat's responses. To generate your own public link, click on "Share" at the top right and copy the link!

Git¶

To actually use homebrew to intall git, I then typed in:

brew install git

To check if Git was installed, I typed in

git ---version

It responded properly, telling me I was on version 2.39.4 (Apple Git-154).

Next, to set up my Git identity, I set my name and email so that my commits are identified by entering:

git config --global user.name "<Your Username>" 
git config --global user.email "<Your Email>"

SSH Key and GitLab¶

To generate a new SSH Key, I used the following command:

ssh-keygen -t rsa -b 4096 -C "27wuk@charlottelatin.org"

and I pressed Enter to use the default file location in which to save the key.

To add my SSH key to the SSH agent, I started the SSH agent in the background with eval $(ssh-agent -s) and added my private key to the agent using ssh-add ~/.ssh/id_rsa.

When I tried to copy the public key using clip, it did not work. I consulted Chat for how I can visually access my SSH key and it told me to type in cat ~/.ssh/id_rsa.pub

It was also very helpful in clarifying for me that - Key type: ssh-rsa indicates it's an RSA key. - Key data: The long string of characters between ssh-rsa and == is the actual key.

Chat's method worked and I saw my ssh key as exactly how it outlined in its clarifications, followed by my email.

Note: Make sure you do not share your SSH key ANYWHERE. I was thoroughly warned about the dangers of recklessly doing so before starting my setup, so I consulted Chat with that in mind and specifically avoided sending it in my prompts. It's also best if you do not share your email.

To paste the key into GitLab, click on your profile icon → edit profile → SSH Keys on the left side dropdown → add new key. Paste the entire string, from ssh-rsa to the end of your email, into the designated text box. Give it a title as well.

Cloning Your Repo¶

In terminal, I entered

git clone git@gitlab.fabcloud.org:academany/fabacademy/2025/labs/charlotte/students/kathryn-wu/.git

I wanted to be sure that the SSH key is properly set up so I consulted Chat for how I would do that. It told me to type in ssh -T git@gitlab.fabcloud.org and I was properly welcomed.

According to Chat, if I entered ls, I should see a folder with my repo's name, which I did!

However, when I entered cd kathryn-wu it would tell me cd: no such file or directory: kathryn-wu, which was weird because I fould find the folder through my file finder.

I realized that I needed to enter the entire path to that folder in order for its contents to be listed.

It did not give me an error this way and also showed up accurately.

MKDocs¶

I needed to download Python 3.13.1 through the Python website before I could intall MKDocs.

Once I did, I went to Terminal and used the command pip install mkdocs. It did not work, and so I again used Chat to help me troubleshoot. It first recommended that I use pip3 and also suggested I try pip3 --version to first check if I actually had pip. It told me that I have version 24.3.1, which probably came with my downloading Python.

Since this change seemed to work, I used pip3 instsall mkdocs which worked! I also checked mkdocs --version to see if MKDocs installed properly, which it did as Terminal told me I had version 1.6.1.

At this point, I started to deviate from the AI Workflow resource and the slides. In retrospect, I have should used the Fab Academy Student MKDocs Template (which I highly recommend) earlier on in the process, as opposed to blilndly setting everything up my own.

Creating the Project¶

To make a new MKDocs project in my repo folder, I entered mkdocs new my-project and opened the file to VS Code, which I also already had downloaded. I played around with the code a bit, changing the heading to "Fab Academy Documentation."

Credits to this MKDocs user guide, which I used to learn what changes to the basic code do.

site_name: "Fab Academy Documentation"
nav:
- Home: index.md
- About: about.md
- Assignments:
 - 'Pre-Fab Academy': assignments/prefabcademy.md
 - 'Week 1: Project Management': assignments/Week1.md
- Projects: projects.md

To check if my changes went through locally, I typed in mkdocs serve into Terminal. It sent back a response ending with the link http://127.0.0.1:8000/.

127.0.0.1 is the loopback address, also known as localhost. It refers to your own computer, meaning the server or service is running locally on your machine.

800 is the port number on which the server is running.

On the local server, I saw the basic index.md page of Markdown. I tried making a change again, and it updated almost perfectly synchronously.

site_name: "Kathryn Wu Fab Academy Documentation"

I was really excited that my site was working, even just locally, so I searched the web for some tutorials for customizing MKDocs. I found this Material for MKDocs Youtube tutorial that taught me how to change the font, colors, theme, and the ability to toggle between light and dark mode.

Following the tutorial, I tried changing the theme to 'Material', but it did not work and an error showed up on VS Code.

I had no idea why Material was not an available theme, but after asking Chat, I realized its because I have to manually install the theme. If I looked closer at the wording of the error, it did say available installed themes

I tried to intall it using pip3 install mkdocs-material. It seemed to have installed but would not show the updates when I opened it in the local server. I tried directly following the video instead. It had me use a virtual environment, an isolated environment for my project that ensures that dependencies and packages for one project do not interfere with those of another.

I tried opening the local server again and it worked!!!

Issues Working in my Repo¶

I tried to commit these changes by going into the Source Control tab and clicking the commit button.

The way I now do my staging, committing, and pushing (and that always works) is different and I personally prefer it. - I open a new Terminal in VS Code and type in git status. It should have line(s) of file names in red that indicate modificatioins to those respective files. Here, you can double check that all the modifications you made have registered (make sure you have saved all changes using ctrl+s). - Next, I use git add <file name> < file name> to add the files you want to stage for the commit. The file names can be copied and pasted from the previous Terminal response. - To double check, I always go with git status again. The files you added and want to commit should now be green instead of red. - To commit, I enter git commit -m "<explain your commit>". In my experience, I always needed to add a message and git commit alone did not work. - Again, I use git status to check the commit went through. You should get a response of something listing all the file changed, number of insertions, deletions, etc. You should also see something like Your branch is ahead of 'origin/main' by 1 commit.(the number of commits varies with how many commits there are, obviously.) - Finally, git push origin main to push your commits to your remote repository. If you chose to password protect your SSH key, it will ask for that password. After all this, git status should say:
Your branch is up to date with 'origin/main'. Nothing to commit, working tree clean.

I was thrown off by the blue clock, the commit button being greyed out, and the blue progress bar continually cycling. I knew that actions for Git would receive a symbol indicating their progress/success, so I thought it was an indication that my commit did not go through. I ran git status and it told me I was ahead of main by 1 commit and to push it.

I ended up doing that and my my-project directory, which contained my mkdocs.yml file, showed up on my remote repo.

I clicked on the link to my documentation site that was given by Fab Academy, but the HTML template was still the one that showed up. When I went through the directories, I realized that the 'public' folder is what contained the HTML template's code. Because I am using Markdown and not Python, I deleted the public folder through:

rm -rf public → git add -A → git commit -m "Remove public folder and HTML template" → git push

After that, I referenced the Fab Academy student template for MKDocs and saw that the .gitlab-ci.yml file was different than what my unedited one was. However, when I tried to edit the file, I was not able to open it and it was hidden. When I entered ls -a, it showed up, but not in VS Code. To get it to open, I had to go through GitLab → Open in your IDE → Visual studio code ssh. I then changed all the code within the file to be the same as what was inside the student template one.

I pushed this change and expected it to have replaced the HTML with my MKDocs site, but it did not. I was really lost because I had deleted the public folder so there should not have been any conflict with the HTML code. I went into Build → Pipelines and saw that my pipeline jobs after deleting my publics folder were failing.

This was when I began to question whether I was supposed to delete the public folder. I went into the .gitlab-ci.yml file and part of the code was

script:
   - time mkdocs build --site-dir public
 artifacts:
   paths:
     - public

which led me to believe the public folder was necessary for the MKDocs website to work.

In my panic, I impulsively 'remade' the public folder with 'Public'. It obviously did not work because it did not have any of the files the original public had and was also case-sensitive different from what it was in the code.

Then, I remembered GitLab has version control, which means I should be able to undo the deletion. I went back into my pipelines and reverted the removal of my public folder.

At this point, I was completely lost and not sure how to proceed, so I referenced previous fab students' repos (Angelina Yang and Adam Stone). I noticed that none of them had public folders, which left me utterly confused.

It was around this point that I emailed Dr. Taylor for some advice. He recommended that I look at prior documentation and dig into the pipeline feedback and search its meaning. He also noted the multiple public folders that I was not sure how to deal with (I thought it was pointless to try to delete them if my pipeline jobs were all failing). He also suggested taht I might have some items in the wrong locations and to reference other GitLab repos to see the file organization.

I think this entire mishandling could have been avoided if I thought each of my decisions through and did not make rash decisions. I think I was too easily swayed by self-doubt and that led me to stray away from the right path I had been on.

Using the Student MKDocs Template¶

When one of my peers, Angel Fang, who I knew also chose the MKDocs route, got her website set up, I asked her about her process. She told me that she used the Fab Academy Student Template. Before she told about this method, I had not considered uploading the MKDocs template into my own repo.

In more detail she told me that she downloaded the entire Fab Academy MKDocs template into her local repository, replacing the files from her given repo with the MKDocs template.

When I went into my files to find the one to move the MKDocs template into, I noticed that I had two kathryn-wu files.

I tested them both to see if their deletion would affect the parent folder kathrynwu and both of them let to the same result, so I randomly chose one to open into VS Code.

This is what the repository folder hierarchy looked like with the MKDocs template added.

I selected all the files under the MKDocs template and moved them to be under my-project.

Because I wanted to preserve the mkdocs.yml file I created on my own and already edited, I swapped the files so that everything that used to be under my-project was moved under the student template directory. Part of it was also that I was paranoid about making more deletion blunders.

I had issues committing these actions, however, as I kept getting the alert:

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        fabacademy-student-template/

Chat helped and explained what the issues meant: - Git detected that fabacademy-student-template is itself a Git repository (it has a .git folder inside it). - Git is warning you that if you include it like this, anyone who clones your repository won't get the content of the fabacademy-student-template unless they know how to clone it separately or you manage it as a submodule.

And gave me the possible solutions of removing it as a nested Git repository using rm -rf fabacademy-student-template/.git, then re-add the directory git add fabacademy-student-template, commit the changes git commit -m "Removed nested Git repository from fabacademy-student-template", and finally push the changes with git push origin main.

Finally, it told me that my branch is up to date and my working tree is clean. I was also confident enough to delete all my unnecessary folders using rm -rf Public public.

After comparing my repo to others, I noticed that I had my docs and other sub-directories and folders under the my-project directory, an extra layer that others did not have. I did this by entering mv my-project/[file/folder name] . [file/folder name] (inside my-project)is what I wanted to move. . is the current directory and the root of my repository.

It worked the way I expected it to and my site also finally worked!!! But I did notice the unusual fabacademy-student-template 78f65f88 file. I assumed that it was the result of my actions of removing it as a nested Git repository. Before deleting it, I copied some important sections of the code from the first mkdocs.yml file (I was particularly attached to the part that allowed me to toggle between dark and light mode with icons).

After doing so, I deleted the file and having version control was also of consolation.

Interestingly enough, my pipeline jobs began to register as check marks after I moved the subfolders and files out of main folder and deleted the main folder.

I committed the aforementioned changes to my mkdocs.yml file but my website did not change even after I pushed. I checked on terminal through mkdocs serve and it told me it was an issue with git revision date localized. Chat told me it likely meant my MKDocs configuration included the plugin, but it was not installed in my Python environment. The reason I lacked it is proobably in the nature of how I copied the MKDocs template.

So, I tried intalling it by running pip3 install mkdocs-git-revision-date-localized-plugin to install the missing dependency so that MKDocs could process my site correctly.

And my website worked!!!

Image Resizing Tutorial¶

Hack for Extracting Images from Docs¶

All of the documentation I had done so far was on a Google Doc, where I pasted all of the screenshots I took throughout the setup process. Because my screenshot setting was set to clipboard, none of the photos were saved to files. I was worried I would have to take screenshots of my screenshots, which would have been incredibly tedious.

Thankfully, a peer from my lab, Angel Fang, let me know about her shortened process. She documented the same way in Google Docs and found a shortcut to access all of her images.

File → Downloads → Web Page (.html, zipped)

In my files finder, under a folder named after the doc, I was able to extract all of the .png images that were included.

XnConvert Resizing¶

I used this XnConvert Tutorial for everything documented in this section.

I first downloaded XnConvert from the app store. Through the input tab, I added my files.

I then moved into the Actions tab, to add action → Transform → Resize.

I changed the width to 600 px and height to 400 px, keeping the ratio.

Next, I went to the Output tab and chose the folder I wanted my resized images to be saved in.

Note: The images can be saved directly into your repo. If you are using the student MKDocs template, that would be under Images.

You can also choose the format you want your images to be saved as. I saved mines as JPG - JPEG/JFIF. You also need to name the images, which does not have to be done individually. The hashtags indicate an ordered numbering, the start index of which you can change.

Finally, click convert. XnConvert is really efficient and all of my 28 images were converted almost immediately. You can check if the images saved properly by checking the folder you chose the images to be saved in.

If it contains everything you want, you can close XnConvert!

Overview¶

This week was like nothing I had ever learned before and easily one of the most challenging and morale-draining. Frankly, before starting, I was incredibly intimidated and could not mentally comprehend how pushing, pulling, commiting, branches, etc. worked for GitLab. For this assignment, I think kinesthetic learning was best for me, but it came at the cost of blind exploits. I encountered a LOT of roadblocks, which I solved with the help of ChatGPT. Troubleshooting with AI taught me how to be very intentional and specific with my prompting. However, seeing my site all set up made everything infinitely worthwhile.

Helpful Links and References¶

Last update: February 19, 2025