You are not Logged In!

Difference between revisions of "Public:GitHub"

From Illini Solar Car Wiki
Jump to navigation Jump to search
imported>Amalia
 
(190 intermediate revisions by 14 users not shown)
Line 1: Line 1:
 +
''For Managing GitHub see: [[GitHub Management]]''{{RemarksBox Info
 +
  | Title      = Note
 +
  | 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.
 +
}}
  
−
__TOC__
+
[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 to push/pull their changes to. For us, that is on GitHub. If you do not currently have a GitHub account you will need to make one. Please make sure your GitHub account has your illinois email address on it (either as primary or secondary) so that we can easily add your account. 
  
−
{REMARKSBOX(type="note" title="Note")}This page is currently in development as is GitHub organization. This page currently exists to define how the github should operate. The GitHub will then be brought up to this spec. - Jonathan (23 Feb 18){REMARKSBOX}
+
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.
  
−
Illini Solar Car has several git repositories used for different things. '''If you haven't set them up yet, read this: ((Github Setup)).'''
+
== Active ISC GitHub Repos ==
  
−
{TABS(name="git_repo_tabs" tabs="PCB|FW|Tutorials|Useful Commands")}
+
=== 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
 +
** [[Github/FW-MCC]] - MCC Firmware
 +
** [[Github/FW-BMS]] - BMS Firmware
 +
** [[Github/FW-Wheel]] - Wheel Firmware
  
−
== PCB==
+
=== Telemetry ===
 +
* [[GitHub/Telemetry]] - the telemetry application
 +
* [[GitHub/Athena-v2]] - race strategy software
  
−
Our PCBs are developed in ((KiCad)) and are stored on GitHub. Our libraries are stored in a separate, public repository which is submoduled into the PCB repo.
+
=== Shared ===
 +
* [[GitHub/CAN]] - defines our CAN Bus Specifications for firmware and CAN
 +
{{Collapsible Box|title=All GitHub Subpages|content={{Subpages}}|autocollapse=true|width=}}
  
−
In order to get the PCBs onto your computer, use -+git clone <repo> <nowiki><nowiki>--</nowiki></nowiki>recursive+-. The -+<nowiki><nowiki>--</nowiki></nowiki>recursive+- option looks for submodules in the repo and clones them into the correct directory. If this option was omitted during the initial clone, run the command -+git submodule update <nowiki><nowiki>--</nowiki></nowiki>init+- to find any un-cloned submodules and clone them.
+
== 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.  
  
−
Once you have the PCBs cloned onto your computer, you should be able to open them and edit them without any issues. If you have any trouble with this, either the project is setup incorrectly, or the repo was cloned incorrectly
+
=== Linux ===
 +
You are done, it ships with git - congrats! {{Emoji Grin}}
  
−
The following describes the process for editing PCBs without changing libraries:
+
=== MacOS ===
−
* Edit the PCB files
+
Many Macs also ship with git, you can check by running <code>git --version</code>. It will either tell you the version or how to install it.  
−
* Stage the changes for the next commit using -+git add <files>+-. To stage all changes use -+git add .+- or -+git add -a+-.
 
−
* Commit the changes using -+git commit -m&quot;<commit>&quot;. Include a useful message to help people reading through the history see what was done.
 
−
* Push the changes to GitHub using -+git push+-
 
  
−
Editing libraries requires a different process, but it's the same whether editing them alone, or along with PCBs.
+
=== Windows ===
−
* Edit the libraries and PCB files
+
On windows you need to install git, we recommend git bash for windows:
−
* Ensure your working directory is the -+Libraries+- directory. This is to ensure changes are being made to the library repo, instead of the PCB repo.
+
* Download Git Bash for Windows: https://git-scm.com/downloads
−
* Stage( -+git add+- ), commit( -+git commit+- ), and push( -+git push+- ) the changes as described above.
+
* Run the Installer
−
* Change your working directory to the PCB repo
+
* When ''Adjusting your PATH environment'', I recommend selecting "Use Git from Git Bash" and not using it from the Windows command prompt.
−
* Stage your changes. '''Make sure''' -+Libraries+- '''is included or the changes in the libraries will not be seen by the PCBs'''.
+
* When ''Configuring Line Ending Conversion'' please use the default for your operating system unless you know what you are doing.
−
* Commit and push as above.
 
  
−
Whenever changes are made on another computer, you need to get the changes with the following process:
+
== Using Git and GitHub ==
−
* Pull the changes to the PCB files with -+git pull+-
+
If you're new to git and/or github there are 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.
−
* Pull the changes to the library files with -+git submodule update --init+-. '''Make sure to do this step every time as it isn't always clear that libraries were changed and not doing it will make it impossible to open the PCBs'''
 
  
−
The following explains what to do when starting a project:
+
=== General Guidelines===
−
* Create and checkout a branch for your project in both the PCB and Libraries repo
+
* Commit often (but not too often)
−
* Create the file structure that follows the ((Standards|Storage Conventions))
+
* Make your commit messages useful
−
* Commit both the library and PCB repo
+
* Pull often!
−
* Create a schematic and have fun!
+
* 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
 +
[[File:Gitworkflow.png|frame]]
  
−
/////
+
=== How Git Works ===
 +
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.
  
−
== FW (Firmware)==
+
On your computer you will have 3 distinct areas:
 +
* Workspace
 +
* Staging Area
 +
* Repository
  
−
This repository is for the vehicle firmware (i.e. all on-board software and only on-board software). The organization of this repository will follow GitFlow. Please [https://datasift.github.io/gitflow/IntroducingGitFlow.html read more about GitFlow.]
+
'''The Workspace'''
  
−
[[File:46]]
+
This is the files you see on your computer and where you are actively working.
  
−
The above image shows the flow of GitFlow. We will utilize that system as follows:
+
'''Staging Area'''
  
−
=== Master===
+
Once you have some files ready to go you put them in the staging area. You stage a specific version of a file, Git will keep track of the specific version you stage (via `git add <filename>`) and further changes to that file will not be in the staging area until you stage the file again.
  
−
=== Hot Fix===
+
'''Local Repository'''
  
−
=== Release===
+
Once you have all the files for this change ready to go you can officially add it to the git history by putting it into your local repository. Next time you push it will also be added to the remote repo. Note that these don't have to be complete changes. You can commit partial changes or the various steps, and this is encouraged, so that you don't lose work and can rollback to intermediate versions later if something changes or goes wrong.
  
−
=== Development===
+
The diagram to the right also shows that commands to use to get between the different parts. Read our [https://github.com/IlliniSolarCar/git-cheatsheet Git Cheatsheet] for more on how to use each of this commands, I reccomend keeping this open to reference while looking through the cheatsheet.
  
−
=== Feature Branches===
+
=== Try it Out ===
 +
Now that your know a bit about what is going on, why not try it out and see git/GitHub in action! A good way to do this is to do GitHub's [https://guides.github.com/activities/hello-world/ guided hello world activity], this should take you less than 10-15 minutes!
  
−
/////
+
== GitHub Tips ==
 +
Using Git Effectively is an important part of being a contributor to the Electrical and Telemetry groups. Here are some tips for doing so:
 +
* Make sure people can figure out who you are on git - either from a picture or your username being obviously related to you
 +
* Pay attention to the other pull requests and issues happening in the repos you work on
 +
** Its good to see what others are working on
 +
** See how reviews go and what is looked at
 +
** Give input!
 +
* Set up Personal Reminders for ISC: https://github.com/settings/reminders
 +
** The Illini Solar Car Organization on GitHub is linked to the ISC slack, you can set GitHub to send you daily summaries and/or real-time notifications for any of:
 +
*** Your Pull Request being reviewed
 +
*** Your Pull request failing a check
 +
*** Your review being requested
 +
*** And more!
 +
** We reccomend at least getting notifications for your PR being reviewed and people requesting your review on a PR, that way the info doesn't get lost in your email and you can respond timely!
  
−
==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.
−
[https://git-scm.com/book/en/v2 Github manual]
+
* [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://gitref.org/index.html Another good Git reference]
+
* [http://www.ndpsoftware.com/git-cheatsheet.html Interactive Git Cheatsheet]
−
 
+
* [https://git-scm.com/book/en/v2 Git manual]
−
[https://www.youtube.com/c/githubguides Github video guides]
+
* [https://www.youtube.com/c/githubguides Github video guides]
−
 
+
* [https://try.github.io/levels/1/challenges/1 Interactive intro to github]&nbsp;
−
[https://try.github.io/levels/1/challenges/1 Intro to git]&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]
−
[http://learngitbranching.js.org/ Git branching]
+
* [https://www.lynda.com/Git-tutorials/Git-Essential-Training/100222-2.html Lynda.com tutorial]
−
 
+
* [https://hkn.illinois.edu/assets/presentations/git.pdf Git Presentation by Dave Boutcher of Ocient]
−
[https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ Git merge conflict resolution (a EE successfully followed these instructions)]
+
{{Platforms Navbox|collapsed=}}
−
 
 
−
I (Tony) didn't know where to put these but I wanted to get them on the wiki so they were here and people could see them. Feel free to edit this if I don't get around to it soon.
 
−
 
 
−
[https://www.lynda.com/Git-tutorials/Git-Essential-Training/100222-2.html Lynda.com tutorial]
 
−
 
 
−
<nowiki>http://www.ndpsoftware.com/git-cheatsheet.html
 
−
 
 
−
</nowiki>
 
−
 
 
−
/////
 
−
 
 
−
==Useful Commands==
 
−
 
 
−
==Moved from main elec page==
 
−
 
 
−
To push a PCB you've just started working on
 
−
* Checkout a new branch
 
−
* Check the status
 
−
* Add files you want to commit
 
−
* Check the status
 
−
* Commit the files
 
−
* Push your changes
 
−
 
 
−
To start editing a PCB
 
−
* Checkout the branch with the PCB
 
−
* Edit the PCB
 
−
 
 
−
To push changes to a PCB that already exists
 
−
* Check the status
 
−
* Add files you want to commit
 
−
* Check the status
 
−
* Commit the files
 
−
* Push your changes
 
−
 
 
−
Neither the PCB nor the FW repositories will let you push changes to master. When you finish a PCB, it needs to be merged using a pull request.
 
−
 
 
−
{TABS}
 

Latest revision as of 14:16, 13 August 2023

For Managing GitHub see: GitHub Management

InfoIcon.png 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 to push/pull their changes to. For us, that is on GitHub. If you do not currently have a GitHub account you will need to make one. Please make sure your GitHub account has your illinois email address on it (either as primary or secondary) so that we can easily add your account.

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 Lead or Telemetry Lead.

Active ISC GitHub Repos

Electrical

Telemetry

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 git and/or github there are 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
Gitworkflow.png

How Git Works

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

This is the files you see on your computer and where you are actively working.

Staging Area

Once you have some files ready to go you put them in the staging area. You stage a specific version of a file, Git will keep track of the specific version you stage (via `git add <filename>`) and further changes to that file will not be in the staging area until you stage the file again.

Local Repository

Once you have all the files for this change ready to go you can officially add it to the git history by putting it into your local repository. Next time you push it will also be added to the remote repo. Note that these don't have to be complete changes. You can commit partial changes or the various steps, and this is encouraged, so that you don't lose work and can rollback to intermediate versions later if something changes or goes wrong.

The diagram to the right also shows that commands to use to get between the different parts. Read our Git Cheatsheet for more on how to use each of this commands, I reccomend keeping this open to reference while looking through the cheatsheet.

Try it Out

Now that your know a bit about what is going on, why not try it out and see git/GitHub in action! A good way to do this is to do GitHub's guided hello world activity, this should take you less than 10-15 minutes!

GitHub Tips

Using Git Effectively is an important part of being a contributor to the Electrical and Telemetry groups. Here are some tips for doing so:

  • Make sure people can figure out who you are on git - either from a picture or your username being obviously related to you
  • Pay attention to the other pull requests and issues happening in the repos you work on
    • Its good to see what others are working on
    • See how reviews go and what is looked at
    • Give input!
  • Set up Personal Reminders for ISC: https://github.com/settings/reminders
    • The Illini Solar Car Organization on GitHub is linked to the ISC slack, you can set GitHub to send you daily summaries and/or real-time notifications for any of:
      • Your Pull Request being reviewed
      • Your Pull request failing a check
      • Your review being requested
      • And more!
    • We reccomend at least getting notifications for your PR being reviewed and people requesting your review on a PR, that way the info doesn't get lost in your email and you can respond timely!

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.

ISC Online Platforms
Communication
Data Storage
(Social) Media
This is all active platforms the team uses. See Online Platforms for previously used or considered platforms
Retrieved from "https://wiki.illinisolarcar.com/w/index.php?title=Public:GitHub&oldid=26732"