Corey Rice: Fab Academy 2017

Principles and Practices, Project Management

Learning outcomes:

More concrete evidence:

Working Through a Git Tutorial

I started by looking into Git. What it is, and what the common vocabulary for the system must be. I was fascinated to learn that it is a distributed source code management system, and why that is a thing. Vauge memories of these ideas came back from when I first encountered github.com, and did a little research to verify that it was a safe website for downloading Arduino code and libraries.

For a little guidance on this journey, I went out to dinner with an old friend who is a developer for a local company. I asked him to give me a crash course in Git and an overview of the relationship between HTML and CSS. He happily obliged, and I appreciated the jumpstart into the week's assignment. After dinner I filled my time with YouTube tutorials on Git. Per ususal, late evening videos are best watched in bed. These served as an adequate lullaby. When I woke up, Git tutorials were still rolling on autoplay.

Thursday I went into school and during my breaks from teaching I found a useful tutorial to walk me through the steps of Git. I also downloaded Git for Windows, so that I could practice with a local pair of repositories as I went along with the tutorial. I needed a simple file that I could change for sample commits, so I quickly made a simple txt file: helloWorld.txt. The entire content of the file started as one line of text: simple text file for testing... This would be all that I needed to get started.

I played with this file and two folders I had made on my local drive to act as both local and remote Git repositories: ‘gitfolder’ and ‘gitclone’ Largely, I just followed the instructions of the tutorial. Though, I did run into some difficulty when trying to move files between repositories for the first time. It seemed reasonable to me at the time that the file locations in the tutorial might be different from my own computer's. So I did not properly link the repositories in my first go around. This gave me errors. Making the connection seemed palpable, but I was stymied.

After a break to teach a few more classes, I was back at it again. This time I switched back to completely matching the commands of the tutorial, except for the most obvious places where my folder names must be substituted. It worked. I was able to make my first successful change to the gitclone version of the file, commit the change and then push the change to the gitfolder version. I did run into another struggle during that slowed me down for a bit: I did not init the gitfolder as a ‘bare’ repository, so I did not have permission to push to the gitfolder from gitclone. However, I worked around this by simply changing my directory to the gitfolder itself and fetching the changes instead. After two tries of this, I felt more confident that I understood the process. Certainly not a 100% understanding, but I had the fundamentals. Finally, I spent some time reading the book ProGit to further connect my flegling understanding of Git.

Making a Website from HTML and CSS

Web development is a very new skill for me. Starting on Friday with W3 Schools lessons for HTML and CSS I was able to quickly develop (or at least utilize) a knowledge base for these critical web languages. I also borrowed an old college book from my roommate: Basics of HTML5 & CSS3. I downloaded VS Code and Notepad++ for development, but ultimately settled on VS Code. I enjoy the dark color scheme, definition tooltips and streamlined interface. Getting started with two new langauges was something of a bumpy road. I made slow progress writing this website by using the language reference pages. The first step was fumbling through some of the basic commands, and just barely getting an HTML document to display what I thought it should with embedded CSS. I tried to make a faveicon in MS paint, and then transitioned to two programs I had long forgotten: Gimp and Inkscape. It took a while, but I came up with an icon that had enough contrast and transparency for a professional look. I started on Friday night, but my work gave way to social endeavors before I had spent more than a couple hours.

Saturday morning I began the web development work again, and after about two hours of further progress, I stopped to meet with a friend. This particular friend is a lawyer and, while I stopped by to help them survey the scope of some home repairs, we talked about licensing the content on my growing webpage. They had limited knowledge about intellectual property, but did eventually reinforce the idea that some sort of simple Creative Commons license would be a good starting point for my work. This recommendation was precautionary. Just in case I developed a fantastic product by the end of this course, and the intellectual property would be of some value. I had looked into such licensing on Friday, but did not implement it as a part of the webpage until after this discussion with my friend. The Creative Commons offers a simple utility for embedding the credentials for such licenses. (I look forward to the Fab Academy lecture on intellectial property.)

A Return to Iterative Design

I continued web development Saturday evening and Sunday morning, with occasional breaks for all of the things that make us human. Since web development is uncharted territory for me, it is something that takes a good deal of experimentation. At about 2pm on Sunday I stopped for lunch. I had spent the weekend trying to build a website that could introduce me to the web and communicate my personality. I was blending the two goals of what am I able to do with code and what do I want to do with design? A discussion with my roommate uncovered a truth: I was not using iterative design. I had spent my weekend lost in the quagmire of learning to code, mixed with website design. Over the last few hours, I had been changing things. Not because they didn’t work, but rather because I didn’t like them.

This is a key distinction. Before I finished the leftover spaghetti lunch, I had decided to change my workflow: I would stop where I was with design. Maybe even simplify things so they don't look broken. My next steps would be to make a file tree that could be useful for the long term future of my website. I would ensure that there are enough folders to be organized, an HTML stub for each page, and a CSS file for my distinct page types. Each of these items would need only minimal editing, and then I could return to my work with Git. I could develop this bare-bones website and commit my progress. I could then push all of this to the Fab Academy servers. Under this plan, I would be able to upload a website that meets the basic requirements of this week's learning goals before the weekend is over. Then extra time could be spent between Monday and Tuesday developing this simplified version of the website into a state that I could consider completed.

Uploading to the Class Archive

Building the file structure and paring down the website versions to their simplest necessary forms went well. I had a few simple pages for “About Me,” “Final Project Ideas,” “Weekly Projects,” and a home page. I also built a ‘stub.html’ that could be used for future weeks' assignments. With a little editing of the CSS and HTML I also ensured that the styles were uniform across all pages and that I could set-up a different looking home page in the future. Once this work was done, I emailed my local instructor, Scott Zitek, for more information about how to upload my web development work. I had looked over some instructions located on the Fab Academy website, for uploading my work using Cygwin and Mercurial. However, it turned out this method was out of date. Zitek directed me to fablabs.io and git.fabacademy.org where I was quickly able to make accounts and get started. At this point, I was thankful for my recent exploration of Git (described above) – it greatly expedited the uploading process at this point. The only real slowdown was establishing my SSH key, and connecting that to GitLabs. However, once this was done, the commit and push process was incredibly simple and I was able to push a few changes to my student folder. Once this process was complete, I was anxious to see my website be hosted on the class archive.

Where I figured that my work may be hosted in the archive, the stub page uploaded by my instructor was still the only thing that I could see. I was surprised to find there would be a hold-up to build the work that I had pushed. Instead, it turned out that I had been adding commits to a branch of the origin repository, which would never make its way online. I still needed to be added to the class by my instructor after making an account in Gitlabs. My first few pushes to GitLabs had come before this authorization and, as a result, had been automatically branched. So the first push that I made (shown below) was to a branch, and I later became able to push to the Origin Master to make this very website.

Git Workflow

The core workflow of Git, a distributed version control system, is quite straightforward once you are a few steps into its implementation. The handshake procedures of setting up an SSH key, as described above, can be a bit more cumbersome. Luckily, it is only necessary to set-up the SSH control protocols once before the first interaction with the remote repository. After this point, the FTP client uses this key to encrypt and secure the transmission of information between the two repositories.

The common Git workflow is impressively simple:

Any changes can be made to the files in the local repository.
Those changes are recognized automatically by Git, and can be checked with a simple git status command.

Before any changes are made to the repository, you need to git pull origin master to make sure your repository is up to date, and will not fork off the master.
All current changes can be added to the Git staging area by using a git add –A command.

The changes to files in the staging area can then be committed by using a git command and modifier: git commit –m ‘a simple comment on changes’

The last necessary step is to push the commits to the remote repository. This can be done with the following command: git push origin master which pushes all local changes to the remote repository through the FTP, back to the repository of origin, specifically in the master branch of that repository.

If you would like to verify that everything went well, it is possible to see a log of all of the commits pushed to the origin using the git log command.

======================= UPDATE ===============================

The old adage still holds: “You only ever really learn when you’re wrong.”

During week 3, one of my local classmates uploaded a huge file to the Git repository. The nice people who run the website quickly shut it all down, so that we would not overload anything. We then had to get our local affairs in order before they would open it all back up. While I am not certain that I was directly responsible for any of that, it is not impossible. However, it definitely did further cement the typical Git cycle of commands in my head:

git pull origin master
git add –A
git commit –m ‘whatever you want your commit message to be’
git push origin master

Always doing these commands in this order is critical in order to not fork off and make a separate branch that will later need merged. Git repositories can work in many ways, but the above is our common workflow for this class.