Skip to content

Week 1 Principals and Practices

This week, my assignments for Principals and Practices were to:

  1. Download, read, and sign the student agreement, and commit the file to my repo.
  2. Work through a Git tutorial.
  3. Build a personal site in the class archive describing you and your final project.

Student Agreement

I found the student agreement here.

You can find where I signed this document here

Work Through a Git Tutorial

I watched this tutorial on Youtube to help me install git because prior to Fab Academy I had never used Git.

I downloaded git for Windows X64 from here

Once you press download, you should get a .exe file. Run the file, read the terms and conditions and press next.

Next choose where Git should be installed. To properly install Git, install it to the Program Files (This should be the default option).

After this, you will be asked what components of git you want to install. For Fab Academy the default selections will work but if you want Git on the desktop, check the box Additional Icons and On the Desktop.

Once you choose the components to install, you will be asked which editor you want to use. Git's default editor VIM works for Fab Academy.

After, you will be asked about adjusting the name of branches in new repositories. Since Fab Academy provides you with a repository, whatever you choose will not affect your Fab Academy repository however if you make a new repository in the future you can change your initial branch name or leave it to automatically set to main.

The next option that will come up is really important, it asks about where you want to use Git. For Fab Academy, we use Visual Studio Code to make our documentation websites, so when asked where do you want to use Git, select the middle option: Git from the command line and also from 3rd-party software. This will allow us to use Git in visual studio.

After that, you will be asked about choosing HTTPS transport backend. For Fab Academy, you will work on group projects where you and your teammates will be working on the same documentation file. Some Fab Academy students work on Windows, some work on Mac, and some even work on Linux. Because of the diverse operating system use in Fab Academy, you should choose OpenSSL and not the Native Windows Security Channel Library because it limits cross platform documentation.

Next you will be asked about configuring the line ending conversations. As a Windows user I selected Checkout Windows-style, commit Unix-style line endings because it is recommended for Windows users who will be working cross platform. You could also select Checkout as-is, commit Unix-style line endings because it also supports cross platform however the first option is easier for windows users.

When asked about Configuring the terminal emulator to use with Git Bash, choose the first option use MinTTY because selecting the windows terminal to use with Git Bash can be a little bit glitchy and not work as well.

This next step is really important because you will be using this command a lot in Fab Academy. When asked Choose the default behavior for Git Pull, select the first option Fast Forward or Merge so you can go to the main branch and not get trapped in a wrong branch.

Git installer will now ask you about choosing a credential helper. Choose the Git Credential Helper because it is cross platform and will help when working with teammates.

Once you press next, Git will install onto your computer and once it finishes, Git will be all set up for Fab Academy!

One more Git tip, in command promt type in 

git

and it will show you all the git commands and what they do!

Build a personal site in the class archive describing you and your final project.

Installing Visual Studio Code

To install VS Code on Windows, I watched this tutorial on YouTube.

First, go to the Visual Studio Code website to download the installer for VS Code.

For me, I downloaded the installer for Windows 10,11.

Once you run the installer, read the License Agreement and if you wish to proceed, select I accept the Agreement.

Next, select where you want VS Code to be installed. For Fab Academy, the default option VS Code recommends will work.

Lastly, on Select Additional Tasks, I selected Create a Desktop Icon so that I could access VS Code from my desktop. Make sure add to PATH is selected (it should already be).

After all of this, you can go ahead and install VS Code!

Setting up your SSH Key

Now that Git and Visual Studio Code are both setup, you can now clone you repository, already made by Fab Academy, to your Visual Studio Code.

I had never cloned a repository before, Andrew Puky, a Fab Academy Graduate from 2025, had great documentation about how to clone your repo so I learned how from him!

  1. To connect your device to Gitlab, you need to generate an SSH key. In Powershell, use this command to generate your SSH key
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Make sure you use the email that you use to sign into fablabs.io with.

  1. When you are asked to choose a location for your SSH, press enter to accept the default location.

  2. It will then ask about a paraphrase, when you type in a paraphrase, the text will not show up for security reasons. I would reccomend setting up a paraphrase because Mr. Dubick told me if someone who knows what they are doing has your SSH and SSH paraphrase could get access to your computer.

  3. Next, you will want to copy your public SSH to put it into Gitlab. Run this command and then copy the output it gives you.

cat ~/.ssh/id_rsa.pub

  1. Log into Gitlab, go to preferences, SSH keys, then paste your SSH key into the box.

  2. Now that you have you SSH Key in Gitlab, you want to make sure you copied it right and that it works. In Powershell, run this command.

ssh -T git@gitlab.fabcloud.org

If you see a message that says "Welcome to Gitlab, [Your Username]!, you have properly setup your SSH!

Cloning your Repository

Cloning your Repository is a fairly easy process. For Fab Academy, since you have to generate an SSH key, you want to clone your repo with SSH.

To do this, go to your repository in Gitlab, press the code dropdown, and copy the URL dropdown that says Clone with SSH.

Next, go into the VS code terminal and enter 

git clone <your SSH repository URL>

This will create a repository folder with all of your files.

Your repository should successfully be cloned to VS Code!

MK Docs Installation

MK Docs isn't neccesary for Fab Academy however it makes the documentation process easier. Instead of writing lines of HTML code, you can type normally for paragraphs, use pound signs for headers and bolding, and still use html for more complicated things like tables.

To install MK Docs, you need python and pip

First, install Python from the Official Python website.

During the installation, make sure to add Python to PATH or else MK Docs will not work.

After Python is successfully installed, you will need to set up pip.

I had never used pip before so I asked Microsoft Copilot:

"I am a Fab Academy student who just installed python and added it to PATH. I need to setup MK Docs so I need pip. Can you tell me how to install pip?"

Copilot told me to first check if pip is already installed. In a terminal, use:

python -m pip --version

If you get an error message, pip is not installed. If you get a version number, pip is installed.

In my case, pip was not installed.

Copilot also told me modern python comes with a built in pip installer. To use it, in the terminal, use the command:

python -m ensurepip --default-pip

After using this command, copilot told me to test again if pip was installed. I ran the command:

python -m pip --version

And now, the terminal responded with a version number. Copilot told me this means pip has been installed, however it isn't in the path yet.

Copilot told me first to find the folder. You can do this by using this command in the terminal:

python -m site --user-base

It should respond with something like C:\Users\your user\AppData\Roaming\Python\Python312

Now that you have the correct file path, in the Windows search bar, open Enviorment Variables.

Once it is open, select Path, press edit, press new, and paste it the response from the terminal. Once you save this, pip should now be installed to PATH!

Install MK Docs

Now that python and pip are now setup, you can now setup mkdocs. In the terminal run:

pip install mkdocs

After this, check if mkdocs is properly installed by doing

mkdocs --version

If you get a version, mkdocs is now setup!

Problems Encountered

This week I only ran into two problem, and one of the problems was pretty scary.

Problem #1, Nuking my Repo

The first problem was deleting everything in my repository. I don't know how, but when I went to make my first commit, it deleted everything and I didnt know this when I pushed it. I told Microsoft Copilot that I accidently made a commit and pushed it to Gitlab where I deleted all my files and need them back. I also provided it with the hash of my commit that went wrong and the commit hash I wanted to revert back too.

Copilot told me to run this command in the VS Code terminal

git checkout e2e79fe721c592004c2eae34cfab2251fc315f82 -- .

This command pulls all the files from the template commit into my current working directory, without switching branches.

Now that everything was restored back into my VS Code, all I had to do was commit and push it to Gitlab and I was all good to go.

Next time, I learned I can use this command in the VS Code terminal

mkdocs serve

So I am able to see my website before commiting and pushing it.

Problem #2, Adding proper copyable code boxes.

On my website, I wanted to add code boxes for showing commands, in a command font, where the user could hover over the box and copy it. 

This is an example of what I am talking about

To do this, there were a few things I needed to do.

But before I tried starting, again, I talked to Microsoft Copilot

  1. First, it told me I needed python downloaded and in the PATH. Luckily, I had already done this to setup my website.

  2. Next, I needed to change the code in my .gitlab-ci.yml and Copilot helped me generate the code. It told me to delete everything in there and replace it with:

image: python:3.10

pages:
  stage: deploy
  script:
    - pip install mkdocs mkdocs-material
    - mkdocs build -d public
  artifacts:
    paths:
      - public
  only:
    - main
  1. Lastly I needed to learn the code to do it. Again, Copilot told me the way to do it is: code box Once I figured this out, I was now able to add code blocks like I have been adding all over my website this week!