2. Project management¶
This week I got started on using Git in order to set up the web page I will use to document my journey through the Fab Lab academy course.
Getting started:¶
My first step was actually downloading Git. I headed for the Git page is downloaded the latest version of the software.
After a laborious installation process, I was now ready to start coding with Git
MkDocks¶
Once Git was set up, I had to install MkDocs. I briefly considered using a different template, however due to my relative inexperience with Git, I decided to play it safe and stick with the “Default”.
Installing MkDocs turned out to be easier than expected, by simply following the instructions on the official MkDocs website.
I opted with the manual installation, meaning that I had to also install Python as well as Pip. Once again this was relatively straightforward. I simply went to the Python page, downloaded the latest version and followed the instructions. It took a little while to complete the installation process, but once that was done all it took was a couple lines of code and I was set up and ready to go.
Once MkDocs was installed it gives us the base template site. In order to change the template we must head to our repository and open the “mkdocs” YML file with your text editor of choice. In my case, the computer defaults to Notepad, but it is recommended to use a dedicated word editing software in order to avoid unnecessary formatting issues.
Once here, we can edit the various values in order to achieve the desired look. This includes font type, general colour scheme as well as a variety of other settings that can be tweaked and changed to suit your own personal preference.
The SSH key¶
Having everything ready it was time to set my SSH key. I mainly followed the instructions found in the Git page. After a little while the key was added and I was ready to proceed!
Setting up the repo¶
Once everything else was ready, it was time to set up the repo. This took a little longer than expected as I familiarised myself with the cd command in the cmd prompt. Eventually I managed to get the directory right, and then it was just a case of imputing the right command. Finally, I had my clone up and ready to go!
After this point it was just a question of going into the files, and start editing the page.
Uploading things¶
Having set the repository it is now time to upload our changes to the page by. First we must open the Git Bash console by navigating to our repo folder, right clicking and selecting “Git Bash Here”. Once its open we can now follow the steps. It is important to note that these steps must be followed in the correct sequence. (note that inverted commas are used to highlight, and should be inputted into the git console)
1: We must type “git status”. This will inform us if there has been any changes done to the online repository compared to our offline one.
2: We must then type “git pull”. This copies whatever changes have been made to the online repository into our offline folder. It is worth it to note that it is not neccesary to do this step unless something has changed in the online data base, however its always recomended just in case.
3: Once our repository is up to date, we must now make the actual changes in the repository, whatever those might be. After completing the desired change, we return to the Git Bash console
4: We must now imput “git add .” This adds our change to the list of outgoing changes.
5: We now type “git status” once more in order to double check that our change has been added. This is not neccesary, but constitutes good practice as it can prevent mistakes due to carelesness.
6: Once we are sure the correct change has been added, we must commit this change by inputting “git commit –m ‘description’” in order to commit the change. (swap “description” for an appropriate description of the change, for refercne sake)
7: Input “git push” to push the files to the main online repository. At this point, check the online repository to ensure the files have indeed gone throught.
8: Finally, navigate to your page and check that the change has appeared in thr way you wished it to.
Problems with Python¶
Over the course of working on my repository, I encountered a strange error when using Git.
When I first set up the repository everything worked as intended, however about a month in I started having an error on the commit step. This to say, I could push and pull files from my local repository to and from the online repository, and I could also make changes on the online repository itself. However whatever changes I made would not commit and as a result would not appear in my Fab Academy page.
I tried various methods in order to solve the issue, including remaking the repository, as well as making a brand new one on a different computer, however none of it worked. Eventually it turned out that the issue was in the version of Python I was using: For some reason, Python Version 3.x has a bug which sometimes causes failures during the commit step. What causes the bug to manifest is unknown (at least to me) but with the help of my tutor we were able to find examples of students from previous years that had similar problems.
The solution turned out to be rather simple in the end. I deleted my repository and uninstalled Python. Then I re installed Python Version 2.x (in my personal case as, of 2019, it was Version 2.7.16) and remade the repository. This then seemed to fix the issue. Note that I did not have to uninstall Git or MkDocs, generate the SHH again or any of the other steps: Only to re install Python and clone the repository to my preferred folder.