1.5. Project Management¶

This week I made my website for my Fab documentation. I used a Macbook Air to complete this process.

Version Control¶

What is version control?¶

Version control is a system that tracks changes to files over time, allowing users to revert to previous versions, collaborate efficiently, and maintain a history of modifications.

There are three main types:

Local Version Control – Saving different versions on your own computer (basically like making copies).

Centralized Version Control (CVCS) – Everyone works from one main server, and changes are stored there.

Distributed Version Control (DVCS) – Everyone has their own full copy of the project, so you can work offline and sync changes later.

What other version control systems exist?¶

Git – The most widely used distributed version control system, supporting branching, merging, and collaboration (used with GitHub, GitLab, Bitbucket).

Mercurial – Similar to Git but with a different approach to branching; known for its simplicity and performance in large repositories.

Apache Subversion (SVN) – A centralized system used in enterprise environments for strict version control.

Perforce (Helix Core) – A high-performance centralized system used in gaming and large-scale software projects.

Bazaar – A flexible DVCS that supports both centralized and distributed workflows.

Fossil – A lightweight DVCS that includes issue tracking, a wiki, and project management tools.

Getting Started¶

I started off using a Github tutorial to learn the basics of pulling, pushing, and merging files. I was ultimately very grateful that I took the time to watch this tutorial because it helped clarify the concepts Dr. Taylor taught us.

We use Git because it supports creating and merging branches and can be used for collaborating fairly easily. It also allows users to revert to previous versions if needed using version control.

SSH Key¶

The first thing I had to do was install Homebrew. Then, I had to add the SSH key to my Gitlab account. I used a tutorial to find my SSH key. First, I had to generate a new SSH key, and add your SSH key to the ssh-agent.

Open Terminal
Paste this text: ssh-keygen -t ed25519 -C “your_email@example.com” with your email address for GitHib
It will prompt you for a passphrase and you can enter one if you want. I started out using a complicated password and later forgot it and had to recreate it. I recommend writing the password down somewhere safe if you do choose a password, or make it something easy to remember and uncomplicated.
Enter eval “$(ssh-agent -s)” in terminal
Enter open ~/.ssh/config. If the file does not exist, enter touch ~/.ssh/config to create the file.
Add the SSH public key to GitHub account. I used another GitHub tutorial to copy my public key.
Enter pbcopy < ~/.ssh/id_ed25519.pub to copy public SSH key to keyboard.
Paste the public key on the SSH key page in GitLab.

When creating my SSH key, I struggled with finding my SSH key in my finder and when I asked ChatGPT, it told me I should use the Command + Shift + . (dot) to find hidden files.

Setting Up Repository¶

Install VS Code: I already had VS Code downloaded, so I did not need to complete this step. VSCode is a powerful code editor used for writing and editing code, managing projects, and integrating with tools like Git.
Clone Git Repository into VS Code:
Download Python:
Install mkdocs: Mkdocs is a static site generator designed for documentation. It converts Markdown files into a well-structured website, making it useful for projects requiring clear and organized documentation. When I was trying to install mkdocs using the pip command I kept receiving an error message: Confused about why I was receiving this error, I asked ChatGPT to help troubleshoot with the prompt “why is it not working?” and a picture of my error. It gave me several commands to enter the terminal, but none of them made pip work correctly. I ultimately realized that I was supposed to select “Add Python to PATH” during installation, but because I have a Mac, that option was not available. I used ChatGPT to help troubleshoot again, but this time with the prompt: “When installing Pytjon on a Mac how do you select “Add Python to PATH” during installation?” This time, I was able to find a process that added Python to PATH in the VSCode Terminal. I used the following series of steps:

These were my outputs: I thought this would allow me to add mkdocs, but I got the same pip error again. I asked ChatGPT once more, but with the prompt: “It still is not working:” and a screenshot of the error again. This time ChatGPT gave me a response that finally allowed me to install mkdocs. I followed a similar process to before, but this time I entered the path name instead of the Python version. I also used pip3 to install mkdocs instead of pip, which I think made the command finally work.

I used the version command to make sure that mkdocs was correctly installed and it was!

There are many errors that come up when using mkdocs serve on a Mac. I tried many methods to resolve these issues and experimented with ChatGPT to try and make it work. Ultimately, a process that allowed the generic mkdocs site IP address to appear was:

mkdocs new filename

cd filename

mkdocs serve

The generic IP address led to the website:

Another error I faced was with docsdir, and this is how I solved it (with ChatGPT’s help):

Another error I faced was with the address, and this is how I solved it (with ChatGPT’s help):

Using Template to Customize Website¶

I decided that I wanted to use markdown and not html when setting up my website. Teddy Warner recommended that we use this template for the markdown files. I struggled a lot with this part, but eventually after figuring it out the first time with the help of my classmates, Angel and Andrew, it made a lot of sense.

Download this template as a zip file.
Open two finder windows at the same time, and open one to the template you just donloaded and the other one to your current git repository.
Clear out your current git repository entirely EXCEPT for the .git folder.
Drag ALL the files from the fabacademy-student-template to your repository folder
Open VS Code and type:

git add .

git commit -m “Choose a message”

git push origin main

This will commit the changes from VS Code to your GitLab website. This commit takes several minutes to complete. Even if the green checkmark apeears next to the commit on GitLab, that does not mean your website is updated yet. It still may take a few minutes. I learned this the hard way. I had gone through all the steps listed above and was very hopeful that my website was going to work, and after I got the green checkmark, I was very excited and went straight to my website, but was disappointed and frustrated that no changes were visible. Several minutes later, I returned to my website, reloaded it, and saw that all my changes had transferred.

After my first commit worked, when I tried to make new changes and commit them, I got an error message saying: fatal not a git repository, and to solve this error, I intially tried consulting with Chat GPT but did not get any helpful responses. I then went to Dr. Taylor, and he asked me if I had Python downloaded (which I did), if I had my SSH key set up properly (which I did), and one more parameter that I also already had set up correctly. He recommended that I just clone my git repository again because that would probably be easier than searching to find the error. I took his advice and cloned the git repository again, and it immediately worked. Surprisingly, several hours later, I was faced with the same issue, so I had to do the same process again, but this time, I had to transfer the images(just dragged and dropped) that I already had set up into the new repository because I had not committed them yet.

The first very important thing that was necessary to successfully download the template was ensuring that the current git repository that was connected to GitLab had the .git folder inside of it. On a Mac, this folder is hidden, so you have to use the keyboard shortcut, Command + Shift + . (dot) to find hidden files (ChatGPT told me this).

Another important thing is that GitLab cannot handle two website customization types, so you MUST CHOOSE between Markdown and html and COMPLETELY REMOVE all the html files if you choose Markdown. I ran into several issues that I struggled with for hours that resulted from me keeping some files of both Markdown and html. Perhaps the most frustrating error I faced throughout this process was when my commits would not go through, and I kept getting pipeline errors. My mkdocs preview was working exactly how I wanted it to, but every time I tried committing it, it would not work, and I would get the red x. I ultimately determined that the reason I kept getting the red X’s was because I was mixing html and Markdown when I needed to entirely stick to one. I thought there were some files I needed to keep from the intiial repository template, but there really were not, so I was struggling to diagnose this issue.

You can also preview the file using mkdocs serve:

I do not know what point this tool started working because I learned about after my website was in pretty good shape, but you can also preview your website using the magnifying glass logo button in the top right corner of VSCode.

Angel also helped me discover that you can commit without using the VSCode terminal through the third button from the top on the far left side of VSCode: . I found that I do not like using the button because it makes the commits take longer and does not have clear error messages when the commits do not work.

Customizing Website and Compressing Images¶

I used this website to change the colors in the theme of my website. I also discovered a trick to compress my images and convert the screenshots to jpegs very efficiently. On a Mac, if you click the mousepad with two fingers on the screenshot you want to convert and compress, there is an option under “Quick Actions” to “Convert Image”. By using this tool, you can convert a png to a jpeg and compress the image to a smaller file size in just one step.

Reflection¶

Overall, I thought this week was pretty fun and a great start to Fab Academy. Once I figured out how to use the template and debug the errors, I was very pleased with the outcome and aesthetic of my website. I am also very grateful for my classmates’ help because it helped speed up the process and improve the experience for everyone. I also learned a lot about using AI to debug and the importance of documenting as you go along because if you try to do all the documentation at the end, you will not remember everything. I was grateful that I took screenshots and started taking some notes as a procedure as I went along at the beginning because after all the debugging I did, there is not a very high chance that I would have remembered any of the initial steps.

I also learned the importance of managing your files because I ended up cloning my git repository so many times with similar names that I could not remember which was the current one. I ended up deleting all of them and then cloning again, but it was a very easily preventable struggle that I should not have let happen. Also, it was very important to know the exact location of the placement of documentation images because that is how they are referenced in the website (based on the file path).

Random Tips¶

To find the home folder on a Mac finder, use command + shift + h

Useful Links¶

AI Help¶

Here are all my ChatGPT searches while trying to figure out how to make my website: PDF 1, PDF 2, and PDF 3

I believe the only chats omitted here are about asking if any private information was shared in the chat or if I deleted something that was private information.

Last update: February 25, 2025