Skip to content

Principles and Practices/Project Management

Goals

  • Plan and sketch a potential final project
  • Read, sign (add your name to) the student agreement and commit it to your repo
  • Work through a git tutorial.
  • Build a personal website in the class archive describing yourself and your final project. Refer to the lecture material for examples.
  • Upload parts 1 and 2, to the class archive.

Prior Knowledge

I’ve experimented with GitHub on my own time, which familiarized me with basics. I understood repos and push requests, however, that was the extent of it. The GitHub presentation filled th gaps in my knowledge, such as pull requests, merge requests, and pipelines. I also learned the concept of version control, which tracks iterations of a project and regulates the changes. It could be centralized or distributed across servers, and since GitLab is distributed, the network often involves collaboration.

Projected Timeline

  • Wednesday
    • Watch boot camp.
    • Work in the lab.
  • Thursday
    • Plan documentation.
    • Determine if my computer will be sufficient for Fab Academy.
  • Friday
    • Begin creating website.
  • Saturday
    • Finish creating website.
  • Sunday
    • Touch-ups and design.
  • Monday
    • Questions and revision.
  • Tuesday
    • Work ahead on CAD.

Actual Timeline

  • Wednesday
    • Watch boot camp from home (snow day).
  • Thursday
    • Purchase new computer.
    • Begin GitLab documentation.
  • Friday
    • Research terms such as RAM and SSD to better understand storage capacities.
  • Saturday
    • Purchase new computer.
    • Begin GitLab documentation.
  • Sunday
    • Continue setting up GitLab file.
  • Monday
    • Restart entire GiLab process due to processing error.
    • Learn that this is not nearly as difficult as I imagined.
  • Tuesday
    • Finish documentation.

Process

Installation

While there are less conventional options, VS Code is universally recommended. I installed Python and GitBash for MkDocs.

  • Installed Python
    • Looked up Python on my browser.
    • Downloaded the latest version for Windows.
  • Installed GitBash
  • Installed VS Code
    • Looked up VS Code on my browser.
    • Downloaded the latest version for Windows.
      alt text

SSH Key Generation

I had to generate an SSH key in order to access code regardless of network. The process involves running simple commands in the GitBash terminal. VS Code works for this process.

  • Generate Key
    • Accessed GitBash terminal.
    • Ran ssh-keygen -t ed25519 -C ““. I put my email in the placeholder and ensured that it matched the one I signed up with on GitHub.
    • Created a passphrase.
    • Typed it again to confirm.
    • Ran cat ~/.ssh/id_ed25519.pub | clip.
    • Accessed my GitLab repo.
    • Clicked Home>Preferences>SSH Keys.
    • Pasted into the box.
    • Committed change.

When entering the passphrase, I was momentarilty confused why nothing I was typing showed up. I then realized that it does register, it is simply a security measure.

MkDocs Installation

Now, I had to install MarkDown on my computer. This generates my website as well.

  • Install MkDocs
    • Accessed VS code terminal.
    • Ran pip install mkdocs-material.
    • Ran mkdocs serve.

Repo Cloning

In order to transfer the git repository to VS Code, I must clone using the SSH key. This way, my edits will transfer directly to the repo.

  • Clone Repository to VS Code
    • Access repo homepage.
    • Find the Code dropdown and copy the clone with SSH.
    • Return to VS Code terminal.
    • Run git clone (pasted link)
      alt text

Pipeline Configuration

Commits run through a pipeline, which is a program that deploys the commit to the website.

  • Creating pipeline
    • Accessed repo homepage>build>pipeline editor.
    • Converted to Github Actions format.
  • Validate pipeline
    • Click validate

This took longer than intended. I encountered issues with syntax as a failed to distinguish between the ci file format and the GitHub Actions workflow format.
alt text

Workflow Creation

I created a .ci file in VS Studios.

  • Pasting file
    • Accessed Teddy Warner’s website.
    • Copied the .ci file
      alt text

HTML Deletion

I ran mkdocs build along the way, figuring that this was a standard command and thought nothing of this. I asked Dr. Taylor why I kept seeing my html site when clicking the url. He explained that the extra files this generates a common error of running an html and mkdocs file at the same time. To fix it, I simply deleted them and committed to the repo.

  • Delete files
    • Access repo
    • Delete files
      alt text

Publishing

I ran a commit through the terminal in order to reliably publish it. From here, the URL updated.

  • Publish URL
    • Ran git add .
    • Ran git commit -m
    • Ran git push origin main
  • Test website
    • Access URL

Since I use VS studio code, I was more accustomed with using the commit button in the Source Control Repositories. Terminal seemed more reliable for website publication. The pipeline succeeded, and I checked the URL. However, only the unmodified html site appeared.

Confused, I ran mkdocs.serve and saw the Markdown site I intended to create. I refreshed several times. I still do not fully understand why this error emerged, however, I never did check file explore so this likely pointed to a faulty file configuration. Since this problem has been present for several days, I considered alternatives. Others suggested that I restart, Dr. Taylor and Mr. Dubick confirmed that this was an ideal decision.
alt text

Restart Everything

Amalia Bordoloi helped me through this process, having done it several times. As it turns out, I did not need to regenerate my mkdocs file. I simply had to delete and add files.

  • File Deletion
    • Accessed File Explorer
    • Clicked This PC>Acer>Users>cheba>
    • Delete all files.

  • File Addition

  • Cloning Repo

    • Accessed GitLab
    • Cloned repo into VS Studio
      alt text

When we previously discussed using the template, I neglected to realize that the template is a repository. I used the mkdocs file on Teddy Warner’s instructional site, since I used it for guidance on the other steps. Now, everything is set up using Julian’s template for the Markdown website.

Edit files

Now, I needed to personalize and document. - Document - Write description in About Me - Paste the Student Agreement - Document this week - Edit homepage

The only confusion I encountered was dash indentaion. I use bullet points for lists and workflows, and often need to create subsections. For example, the timeline sections.

I added the mkdocs video plugin as well as a search plugin so that readers can search for sections. I experimented with hashtags in order to create headers and determined a structure.

Sketch Final Project

I added a sketch and a planning paragraph to the final project page.

Reflection

Considering that most of my issues stemmed from simply not seeing the website, I believe this week introduces complex problems with rather simple solutions. Although GitLab creation is frankly quite tedious, I am very glad I chose Markdown. I vaguely know html commands, however, I would much rather simply write without the interruption of symbols and code.

In hindsight, I should have taken more screenshots during the process. Although I did manage to capture my main issues, I am more text-oriented and prefer to write about issues. Now that I have a functional laptop with more than 4 gigs of RAM, I can collect screenshots throughout the process. Also, I gained a better understanding of outlining processes. I chose to create a projected timeline for planning, then reflect by writing my actual timeline. I enjoy creating workflows, and while I am aware that AI creates these far faster, I add personal notes and extra steps. I often find that workflows use jargon and skip to steps that beginners would fail to grasp, and would not want readers to face the same issue. I decided on making workflows for each week with each ideal step, which typically matches the steps I take. If an issue emerges and my actions differ, I document below the step.

Lessons

  • Since Fab Academy is just starting, ensure that your computer has high enough RAM and SSD to support these apps. You would not want to transfer everything onto another device halfway through. I went by the Fusion 360 recommended specs when considering a device and went to MicroCenter, a store near me.
  • I personally recommend using Markdown. While it takes longer to set up mkdocs files and install Python and GitBash, I find I never struggled with documentaion once I set up GitLab. The syntax is also quite intuitive and allows html plugins. Of course, if you have an html background or just prefer it, then there is certainly no issue with html. Html is the default site which allows simple setup, and more people tend to use it for its conventionality.
  • Configure your pipeline before making changes on your repo. Everything will fail until you add a proper pipeline because it automates your commits.
  • Templates are extremely helpful. Make sure to fill everything in and personalize the files that require you to do so. If you do not want to use one, find a simple naming convention and stick to that.
  • Don’t be afraid to restart. Of course, look into other solutions and troubleshoot, but the steps outlines will guide you through it. If you already typed in documentation, copy it into a text editor - I used Google Docs out of habit - and paste when you’re done. This way you will be re-doing very little.
  • If you want to design your website from the mkdoc file, do it this week! I am working on design now so that I can consistently document later without re-considering my background choices. Take the time to understand image syntax, though, since it will be a priority for future documentation.
  • Screenshot everything. If you are unsure what to screenshot, write or look up a workflow and take a picture after completing each step. It will be quite a hassle otherwise, looking around for the occassional scereenshots that you took. Also, use Windows+Shift+S to screenshot and paste after cropping. This way, your pictures will be quite small and not distract readers with the view of the entire screen.
  • I learned this a couple of days into the week, but bookmark important websites! I have my website, GitLab repo, and Nueval bookmarked. I also have OnShape and SolidWorks for CAD.
Last update: February 20, 2025