GitLab & Nueval
General Overview & Recommendations
Welcome to Fab Academy!
David Taylor (2016), Teddy Warner (2021), Nicholas Niles (2022), Adam Stone (2023), Stuart Christhilf ( 2023), & Griffin Orsinger (2023)
GitLab
Overview
What is Git?
What is Version Control?
As git’s website puts it, “Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency”.
“Version control, also known as source control, is the practice of tracking and managing changes to software code. Version control systems are software tools that help software teams manage changes to source code over time. … Version control software keeps track of every modification to the code in a special kind of database. If a mistake is made, developers can turn back the clock and compare earlier versions of the code to help fix the mistake while minimizing disruption to all team members.” (Atlassian BitBucket)
What is GitLab?
“GitLab is a web-based Git repository that provides free open and private repositories, issue-following capabilities, and wikis. It is a complete DevOps platform that enables professionals to perform all the tasks in a project—from project planning and source code management to monitoring and security. Additionally, it allows teams to collaborate and build better software.” (Simplilearn)
*You will be assigned your GitLab account for Fab Academy. Please be on the lookout for an registration email.
GitLab Login for Fab Academy Git Cheat Sheet Fab Academy Site Template - HTML Fab Academy Site Template - markdown (recommended with Teddy’s directions)***
Important Terms
What is a repository?: A repository a.k.a “repo” is a project containing files and folders. A repository tracks versions of files and folders.
What is a branch?: A branch is a parallel version of your repository. By default, your repository has one branch named main and it is considered to be the definitive branch. You can create additional branches off of main in your repository. You can use branches to have different versions of a project at one time. On additional branches, you can make edits without impacting the main version. Branches allow you to separate your work from the main branch. In other words, everyone's work is safe while you contribute.
What is a profile README?: A profile README is essentially an "About me" section on your GitHub profile where you can share information about yourself with the community on GitHub.com. GitHub shows your profile README at the top of your profile page.
What is a commit?: A commit is a set of changes to the files and folders in your project. A commit exists in a branch.
What is a pull request?: Collaboration happens on a pull request. The pull request shows the changes in your branch to other people. This pull request is going to keep the changes you just made on your branch and propose applying them to the main branch.
What is a merge?: A merge adds the changes in your pull request and branch into the main branch.
Master, Branches, & Merge Request
The goals of Git include speed, data integrity, and support for distributed, non-linear workflows (thousands of parallel branches running on different systems).
Concretely this means that two different persons can work on the same code without hindering each other’s progress. To do so each person will work on their own branch which is a copy of the main code that is located on the branch “master”. When saving a modification, each user commits their changes and explains what has been modified in what is called a merge request.
*This will be especially helpful during group assignments.
GitLab - Web Browser & Desktop Git
Web Browser
This is particularly key here because this means that GitLab allows non-developers—at least people who never learned how to use a version control system, like myself one year ago — to add modifications in the code without having to follow an extensive training in computer science.
Desktop Git Development
As you become more comfortable with GitLab, you will probably want to use Git on your own computer (via the terminal or a Git GUI client). This will allow you to save time because you will have a copy of the repository files on your desktop. Furthermore, you host your site locally and view changes before pushing them publicly.
Navigating GitLab
Repository
To each project on GitLab corresponds a repository. This is where you will find all the files included in your project but also the history of changes and the status of the existing branches. This is the place where you should start when discovering a new project, as you will understand the project’s structure and how contributors work on it.
Status Commit Symbols
Merge Requests
You can start contributing to it by making changes to the code located on the “master” branch. To do so, go to the “Merge Requests” (also called “MR”) section.
Merge Request History
GitHub Course
GitHub is very similar to GitLab
I recommend take the following Introductory Course to GitHub. It will help you gain an understanding of the functionality of GitHub and GitLab.
MkDocs & more
MkDocs
MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introductory tutorial, then check the User Guide for more information. Helpful link: MarkDown & MarkDown Cheat Sheet
You can use the web IDE to edit/code your site in GitLab using MkDocs.
index.md is the Markdown version of the main page for your site.
Neil’s Git Info and Commands-from the class archive
MkDocs Support Links
Helpful Links for MkDocs
Checkout Recent Graduates documentation on using MkDocs and more:
MkDocs web editor
It is almost like writing regular English. Use resources from the internet to learn more about Markdown, as well as HTML5. You can also use a Python plugin.
Project Portfolio Setup
Teddy Warner’s Steps to setting up your MkDocs, Git, Python, local, Visual Studio, and more:
Project Portfolio Setup I would recommend following Teddy’s documentation and then use the Fab Lab MKdocs template in your local repo folder
*This process will give you the ability to develop and code your site on your computer and push/pull your updates to the GitLab website for Fab Academy.
Big Picture Key Steps:
Make sure to DOCUMENT, DOCUMENT, AND DOCUMENT some more!
Tip: Throughout this process make sure you are aware of the specific terminals you are using in different steps, such as GitBash terminal, Administrator Windows Terminal, or Visual Studio Code terminal.
Mrs. Morrow's documentation
Please read through and use Mrs. Morrow’s Project Management documentation. Please use her documentation to support your learning and understanding of setting up your repo and site. Furthermore, her documentation and attention to detail is outstanding and an example of quality documentation. She is a 2022 graduate.
Reset documentation:
Mrs. Morrow talks about the hard reset possibility using the following git command: git reset --hard
Also, Mr. Stone has experience with this topic too.
SSH key in GitLab
1. You will go to your user icon and select “Preferences”.
2. Here you can put in your SSH key, give it a title, and an expiration date.
The following link is for instructions on how to setup an SSH key provide by GitLab.
Helpful link: GitHub SSH Key Info.
SSH key and your computer
Please make sure you are an administrator in the command terminal
A copy of your SSH key is stored in your C: drive.
How to clone a site in GitBash
Copy your clone link from Git Lab and paste into the GitBash Terminal following the command git clone. This will clone your repo locally in your PC’s User folder
Install Visual Studio Code
X
Please use Visual Studio Code. Do not use Visual Studio. They are two different softwares.
GitBash command terminal example
You can also run the commands in the Visual Studio Code command terminal.
$ = administrator
Adding embedded video to your site - site add-on
pip install “mkdocs-video” and add it to your site directory, same as other plug-ins
To add these plugins, in your .yml file, add this to the end of your file
Using this plug-in, you can then use the same syntax that is used for images, with
the exception of in the square brackets, you type [type:video].
If you don’t want to do this, you can
Helpful Problem Solving Links
While in Visual Studio Code
mkdocs serve
This terminal command allows for a test ip address that can be opened in an internet browsers locally on your computer for testing purposes.
Non-terminal process
Dr. Adam Harris’ site on using a non-terminal method.
Site Size & Data Storage
Please try to keep your “repo” size down as much as possible. In other words, keep your storage data low. Here are some tips for doing this:
Nueval
Overview
What is Nueval?
The evaluation process is documented in the Evaluation App: http://nueval.fabacademy.org/
There, Students, Instructors and Global Evaluators have a profile and are able to log in to comment and review comments regarding the evaluation process.
The App is the tool for what is called “continuous evaluation” in which there is a constant stream of assignments being evaluated and passed, by both Instructors and Global evaluators, to have a continuously updated picture of student’s status during the cycle. In addition, students receive continuous reviews that allow informed decisions along the cycle.
Make sure to DOCUMENT, DOCUMENT, AND DOCUMENT some more!
*You will receive an email notification telling you that your account has been activated.
Navigating Nueval
Student dashboard
This app allows students to check their evaluation records and provide feedback to evaluators. For more information see Student Dashboard.
What can be done in the student dashboard:
Customization of Your Website for Documenting
Overview
Using Markdown
Use Markdown to customize your site
Use these resources to learn to customize your site:
MKDocs-Specific Customization & Features
Use this website as a guide to utilizing custom MKDocs features:
https://squidfunk.github.io/mkdocs-material/reference/
Includes tooltips, icons, and more.
Using HTML
Markdown understands HTML, so any HTML can be written into your documentation without any issues.
This makes it super easy to find code examples online and to use more complex methods of customizing your site that Markdown does not allow.
Use this resource to help you:
Need more help?
Any issue you have or thing you want to add to your site can be found online by just googling what you need, use this to your advantage to learn and answer any questions you may have. Most importantly, make sure to link and cite any resource you use to help you on your documentation.
Other Helpful Resources & Information
Expert Network Map
Expert Network Map
Helpful Links for Fab Academy
Wednesday Sessions, as well as Mondays, at at 9:00 AM EST - http://fabacademy.org/2024/video.html Password: 1234
Fab Academy 2024 Assignments and Assessment - This is a generalized schedule for each week that has the assignments and basic objectives.
Fab Academy 2024 Schedule - Past schedule for referencing content and skills
Fab Academy 2021 Schedule - Past schedule for referencing content and skills
Fab Academy 2022 Schedule - Past schedule for referencing content and skills
Fab Academy 2023 Schedule - Past schedule for referencing content and skills
Fab Academy Tutorials - A list of tutorials for different topics covered each week.
Fab Charter - You will copy and paste this into your site/repo along with your typed signature.
MatterMost - This is Fab Academy’s versions of “Slack”. It is a communication and questioning tool.
Videos/Lessons - This will house the videos for each weekly lesson by Dr. Neil Gershenfeld.
Helpful Link - This has documentation for a range of topics, including how to document your work, by Fab Lab Barcelona. This link provides you information that could help you through Fab Academy.
Adam Stone Image Resizer - This is a image compression tool made by adam stone fab academy graduate of fab academy 2023, and you can use it to compress all your images.
**Please make sure to pay attention to Neil’s weekly requirements in the lectures, as well as your instructors. MAKE SURE TO WATCH THE LECTURES WEEKLY!
Make sure to DOCUMENT, DOCUMENT, AND DOCUMENT some more!
Fab Academy Boot Camp & Saturday Morning Support Sessions
January 15-19, 2024 at 9:00 AM EST
Student bootcamp Link:
http://fabacademy.org/2024/video.html Password: 1234
Saturday morning Global Open Time meetings a.k.a “help sessions” at 9:00 AM ET
There will be ongoing open help sessions each saturday morning during Fab Academy. This is led by Adrián Torres, Pablo Nuñez, and Rico Kanthatham, as well as other experts from around the world. More information about can be found on MatterMost in the near future.
http://fabacademy.org/2024/video.html Password: 1234
30-40 hours a week. Time management is important!
Student Bootcamp Schedule 2024
Presentation list
Electronics Libraries & more (<-- check it out!)
Helpful Resource for Electronic and Communication Protocols: Understanding and Selecting in 2024: I2C, SPI, UART Explained
References