Difference between revisions of "Public:GitHub"

Revision as of 00:19, 20 November 2020

	Note
This page is just generally about setting up and using Git and GitHub. See specific instructions for workflows on each repo in their subpages linked below.

GitHub is a website for hosting and working with Git repositories. Git is a distributed version control system for text based files (primarily software) created by the Linux Kernel development team. Unlike most version control systems, it is distributed which means that every single person has the full fledged repository on their machine and thus there is no single point of failure. For collaboration there need to be one copy of the repository that is the origin that is accessible to everyone. For us, that is on GitHub.

GitHub adds many features on top of just git, including issue tracking and projects, Continuous Integration including GitHub Actions, Releases, and more. Below you'll find info for general use of git and links to pages for specific instructions for each of our repos. To get access to GitHub talk to an Electrical Leads (currently: Rahul Kajjam and Jarod Partlo) or Telemetry Lead.

Active ISC GitHub Repos

Electrical

Hardware
- GitHub/PCB - for all boards
- GitHub/isc-hw-libs - hardware libraries for the boards
Firmware
- GitHub/b-fw - Brizo's Firmware
- GitHub/mbed - Operating System for our firmware
Telemetry
- GitHub/Telemetry - the telemetry application
- GitHub/Athena-v2 - race strategy software
Shared
- GitHub/CAN - defines our CAN Bus Specifications for firmware and CAN

All GitHub Subpages

Installing Git

Most of our team members use Git from the command line exclusively, and we recommend that you do too in order to git (haha) on the same page as everyone else.. It will help make sure that you learn and understand the tool and give you the full powers of Git, as most git GUI programs aren't able to provide all the features.

Linux

You are done, it ships with git - congrats! 😀

MacOS

Many Macs also ship with git, you can check by running git --version. It will either tell you the version or how to install it.

Windows

On windows you need to install git, we recommend git bash for windows:

Download Git Bash for Windows: https://git-scm.com/downloads
Run the Installer
When Adjusting your PATH environment, I recommend selecting "Use Git from Git Bash" and not using it from the Windows command prompt.
When Configuring Line Ending Conversion please use the default for your operating system unless you know what you are doing.

Using Git and GitHub

If you're new to Github they're many resources on the internet to learn more about it. Watching some youtube videos on the basics and trying it out by creating your own repository is a great way to get started.

General Guidelines

Commit often (but not too often)
Make your commit messages useful
Pull often!
Keep your branches limited in scope
Name your branches and Pull Requests Nicely
Describe what you did on your Pull Requests
If you aren't sure what you are doing ask for help!
If you think you broke something talk to someone right away!
- It essentially always fixable but we want to do so quickly so others don't run into problems or base their new work on broken things

Git Repository Structure

To the right is a (large) diagram of git. The remote repository is the GitHub repository that you connect to via the lightning (internet). Before we discuss the local parts we need to briefly have an idea of how git stores information. Git does not store every single version of every single file. Instead it stores the "diff" (difference/changes) for each version in the history. This allows it to efficiently store the information of the full history without repeating and wasting a lot of data. This information is stored in the hidden git folders, so what you see for files on your computer is just your active workspace, but all the info about your local repository is there.

On your computer you will have 3 distinct areas:

Workspace
Staging Area
Repository

The Workspace

Tutorials

Git is a super useful tool that is becoming ubiquitous with CS / ECE and more engineering fields. It is used for all sorts of things (not just code) . Version control is incredibly powerful, but because of that it can be hard to learn. Below are some recommended tutorials. Of course, as git was made for code, there is tons of info on the internet. Being good with git will be very helpful within jobs and academics.

@@ Line 1: / Line 1: @@
-{{WIP|Moving to subpages, getting rid of tabs, adding info for the other Repos. This page will turn into generally using github|Jonathan}}
 {{RemarksBox Info
    | Title      = Note
-   | Text       = This page is about the set-up and workflow we use on Github. Other pages are used for how git is used with certain software such as [[KiCad]] or [[MCUXpresso]]. Additionally, it does not include info about github management, teams, and projects as used by Illini Solar Car, which is at [[GitHub Projects|GitHub Projects]]
+   | Text       = This page is just generally about setting up and using Git and GitHub. See specific instructions for workflows on each repo in their subpages linked below.
 }}
-GitHub is a website for hosting and working with [[Wikipedia:Git|Git]] repositories. Git is a distributed version control system for text based files (primarily software) created by the Linux Kernel development team. Unlike most version control systems, it is distributed which means that every single person has the full fledged repository on their machine and thus there is no single point of failure. For collaboration there need to be one copy of the repository that is the origin that is accessible to everyone. For us, that is on GitHub.
+[https://www.github.com/IlliniSolarCar GitHub] is a website for hosting and working with [[Wikipedia:Git|Git]] repositories. Git is a distributed version control system for text based files (primarily software) created by the Linux Kernel development team. Unlike most version control systems, it is distributed which means that every single person has the full fledged repository on their machine and thus there is no single point of failure. For collaboration there need to be one copy of the repository that is the origin that is accessible to everyone. For us, that is on GitHub.
 GitHub adds many features on top of just git, including issue tracking and [[GitHub Projects|projects]], [[Wikipedia:Continuous integration|Continuous Integration]] including [[GitHub Actions]], Releases, and more. Below you'll find info for general use of git and links to pages for specific instructions for each of our repos. To get access to GitHub talk to an {{Electrical Lead|}} or Telemetry Lead.
@@ Line 45: / Line 43: @@
 If you're new to Github they're many resources on the internet to learn more about it. Watching some youtube videos on the basics and trying it out by creating your own repository is a great way to get started.
-= General Guidelines=
+=== General Guidelines===
+* Commit often (but not too often)
 * Make your commit messages useful
 * Pull often!
-* Commit often (but not too often)
+* Keep your branches limited in scope
+* Name your branches and Pull Requests Nicely
+* Describe what you did on your Pull Requests
 * If you aren't sure what you are doing ask for help!
 * If you think you broke something talk to someone right away!
-** It essentially always fixable but we want to do so quickly so others don't run into problems
+** It essentially always fixable but we want to do so quickly so others don't run into problems or base their new work on broken things
+[[File:Gitworkflow.png|frame]]
+=== Git Repository Structure ===
+To the right is a (large) diagram of git. The remote repository is the GitHub repository that you connect to via the lightning (internet).
+Before we discuss the local parts we need to briefly have an idea of how git stores information. Git does not store every single version of every single file. Instead it stores the "diff" (difference/changes) for each version in the history. This allows it to efficiently store the information of the full history without repeating and wasting a lot of data. This information is stored in the hidden git folders, so what you see for files on your computer is just your active workspace, but all the info about your local repository is there.
+On your computer you will have 3 distinct areas:
+* Workspace
+* Staging Area
+* Repository
+'''The Workspace'''
-== Tutorials ==
+=== Tutorials ===
 Git is a super useful tool that is becoming ubiquitous with CS / ECE and more engineering fields. It is used for all sorts of things (not just code) . Version control is incredibly powerful, but because of that it can be hard to learn. Below are some recommended tutorials. Of course, as git was made for code, there is tons of info on the internet. Being good with git will be very helpful within jobs and academics.
-[[File:Gitworkflow.png|thumb|Git workflow]]
 * [https://github.com/IlliniSolarCar/git-cheatsheet ISC Git Cheatsheet]
 * [https://docs.google.com/presentation/d/1-LV8cFV8CfE6pLvHza3WeOPIuVB4yOZinFEIl2e3QEE/edit#slide=id.gc6f73a04f_0_0 ISC Git Presentation on Drive]
-* [http://www.ndpsoftware.com/git-cheatsheet.html Another Git Cheatsheet]
+* [http://www.ndpsoftware.com/git-cheatsheet.html Interactive Git Cheatsheet]
 * [https://git-scm.com/book/en/v2 Git manual]
-* [http://gitref.org/index.html Another good Git reference]
 * [https://www.youtube.com/c/githubguides Github video guides]
-* [https://try.github.io/levels/1/challenges/1 Interactive intro to git]&nbsp;
+* [https://try.github.io/levels/1/challenges/1 Interactive intro to github]&nbsp;
 * [http://learngitbranching.js.org/ Git branching tutorial]
 * [https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ Git merge conflict resolution]