Public:GitHub

{REMARKSBOX(type="note" title="Note")}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. That will be on a page that ((User:weigao4)) needs to make{REMARKSBOX}

Illini Solar Car has several git repositories within our on GitHub. You must talk with an ((Electrical Group Structure|Electrical Lead)) or Strategy & Telemetry Lead so they can give you access to our private repositories. In general, many people use git via the command line. We use it almost exclusively, and you should learn it in order to git (haha) on the same page as everyone else. On most Linux distros this is included in command line. On Mac and Windows you can download git. When "Adjusting your PATH environment," I recommend selecting "Use Git from Git Bash" and not using git in the Windows Command Prompt. When "Configuring the line ending conversions" please use the settings recommended for your operating system unless you know what you are doing.

General Guidelines

• Make your commit messages useful!
• Commit often (but not too often)
• 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

Info on how to use git by group:

{TABS(name="git_repo_tabs" tabs="PCB|FW|Strategy & Telemetry|Tutorials")}

PCB

Our PCBs are developed in ((KiCad)) and are stored on GitHub.The PCB repository is ongoing and will likely continue as the location for PCBs until there is a major change.

The component libraries for PCB design are stored in a repository. This repo is public. It is submoduled into the PCB repo for use in our hardware design.

Our libraries are stored in a separate, public repository which is submoduled into the PCB repo.

Using git for PCBs started in 2017/18 when we switched to Kicad. Before that we used [1] which does not use git compatible files. Our older PCBs may not be on git, rather they should be available on box

Initial Setup

In order to get the PCBs onto your computer, use -+git clone <nowiki>--</nowiki>recursive <repo> <optional>+-. The -+<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>init+- to find any un-cloned submodules and clone them.

Once you have the PCBs cloned onto your computer, follow the instructions to set up ((KiCad)). Once this is done, you should be able to open the latest manufactured PCBs.

To open a PCB that is being designed (i.e. not on master), checkout the branch using -+git checkout <branch> --recurse-submodules+-. If you forget the submodule option, use -+git submodule update+- to get the correct libraries. If you do not have the correct libraries you will not be able to see any components not included in current libraries.

If you cannot get components from our libraries to work for a PCB it may have been designed before the big libraries update that came with Kicad 5. See info on the ((KiCad)) page about upgrading projects.

PCB Repo Workflow

Designing PCB's is not a super collaborative project in a way that multiple people could be working on it at the same time independently. Therefore git is mostly just a versioning tool and the PCB repo is mostly linear. Every PCB will have its own development branch. If needed (there are new parts) it will have its own corresponding branch on the hardware libraries.

When a board is ready for review a pull request will be opened. If applicable a PR on the libraries repo will be opened too. Note that the libraries PR must be merged and the libraries submodule on the PCB branch must be updated to master before it is merged. Pull requests will be merged into master once reviewed and approved.

Boards will only be manufactured if they are on master. Some boards on master may not have been manufactured but in general the master branch is boards that have been made and other branches are boards that are in progress.

Making changes

The following describes the process for editing PCBs without changing libraries:

1. Edit the PCB files
2. Stage the changes for the next commit using -+git add <files>+-. To stage all changes use -+git add .+- or -+git add -a+-.
3. Commit the changes using -+git commit -m"<commit>"+-. Include a useful message to help people reading through the history see what was done.
4. Push the changes to GitHub using -+git push+-

Editing libraries requires a different process, but it's the same whether editing just the Libraries or the Libraries and the PCB files.

1. Edit the libraries and PCB files
2. Ensure your working directory is the -+Libraries+- directory. This is to ensure changes are being made to the library repository, instead of the PCB repository.
3. Stage( -+git add+- ), commit( -+git commit+- ), and push( -+git push+- ) the Library changes as described above.
4. Change your working directory to the PCB repo
5. Stage your changes. Make sure -+Libraries+- is included or the changes in the libraries will not update on GitHub.
6. Commit and push as above.

If you do not do this, git will not have the right libraries associated with your PCB branch. When others open it and update their submodule they won't be able to see the components you added to libraries.

Whenever changes are made on another computer, you need to get the changes with the following process:

1. Pull the changes to the PCB files with -+git pull --recurse-submodules+-
2. If you forgot to add -+<nowiki>--</nowiki>recurse-submodules+-, use -+git submodule update --init+-.

When your board is ready for review

1. Generate manufacturing files and get a ((Requisitions (electrical)|Bay Area Circuits DFM report))
2. Add a zip file of the manufacturing files to the repo\
3. Make sure that everything is pushed so the most recent version of your board is being reviewed
4. Go to the PCB repository on the GitHub website
5. Click on the drop down menu "Branch: master" and click on your branch name
6. Click "New Pull Request" in the button next to the drop down menu
7. Add some sort of comment describing the project and a link to the DFM report, than click the green button that says "Create pull request"
8. If you have made changes to the libraries repeat the last three steps for your branch on the libraries repo
9. On the page for your pull request you will see "Review Required" (you cannot merge into master without approval). In the top right request reviews from appropriate senior team members so that it can be approved.
10. You should also see "Merging can be performed automatically" which is good, once approved the merge will be painless. If you see that the merge "cannot be performed automatically" then you should find out why there is a conflict. Usually there should not be. If you can't figure it out your reviewers can probably help.
11. There will be conversations about approving your merge and you will probably have to make changes. Note that before your PCB is approved make sure that the Libraries branch (if applicable) is merged and your libraries updated to master. Otherwise you will lose your approval for updating that after approval.
12. After someone reviews and approves your pull request, you may get an email or notification

• *it's nice when they tell it to merge for you
• *if they don't, you have to go back to the page and do it
• Special for admins: yes you can bypass checks and merge if you want. Use your power wisely.

{REMARKSBOX(type="errors" title="Location Error")}The following section should be on the Kicad or PCB design page{REMARKSBOX}

Starting a project

1. Create and checkout a branch for your project in both the PCB and Libraries repositories

• * -+git checkout -b <branch>+-

1. Copy the latest template from the -+Dev+- folder
2. Rename your file structure to follow the ((Standards|Storage Conventions)) - you will have to rename the folder and each project file manually

• *Do not rename the -+.kicad_wks+- file or you'll be sorry the nice logo and other settings disappear

1. Make an initial commit to the Libraries and PCB repositories (in that order) as below

• *For the first push use -+git push --set-upstream origin <branch>+- to create the branch on GitHub

/////

FW (Firmware)

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 read more about GitFlow.

Initial Setup

In order to get the code onto your computer, use -+git clone <nowiki>--</nowiki>recursive <repo> <optional>+-. The -+<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>init+- to find any un-cloned submodules and clone them. The submodule in this repo is a fork of mbed, which we don't usually change.

Once you have the FW cloned onto your computer, follow the instructions to set up ((MCUXpresso)). Once this is done, you should be able to flash and debug code on our MCUs.

To open code on another branch, such as a work in progress or a new feature that needs more testing, checkout the branch using -+git checkout <branch> --recurse-submodules+-. If you forget the submodule option, use -+git submodule update+- to get the correct version of mbed.

The above image shows the flow of GitFlow. We will utilize that system as follows:

Feature Branches

/////

Strategy & Telemetry

The strategy and telemetry group currently has 3 repositories: Telemetry, data-analysis, and Athena-v2.

Information about these repositories and their setups can be found in the README.md files in each repository.

clone the repository using -+git clone <repo> +-

About Repos

The Telemetry repo primarily holds the code for the ((Telemetry|telemetry)) application, the app that allows us to view and analyze car data in real time to diagnose issues and make informed decisions.

The data-analysis repo hold code used to analyze datalogger race data after the races to better understand the car and its performance.

The Athena-v2 repo has code that is currently an in-progress project currently delayed until more man and woman power is available to code. The project is a car simulation and optimizer to determine optimal strategy decisions in a calculated and methodical way.

Workflow

The workflow of branches and commits should be similar to how the FW repo works. All work should be done in separate branches if multiple people are working on one feature, they should each have their own branches and merge them together when possible. Branches should not be merged into master until they are known to work without breaking the system.

To merge a branch in to master a pull request should be made and at least two reviewers should be requested. Once these reviewers have approved the pull request can be merged into master.

If changes need to be made quickly and shared and there is not time to follow the review process (for example during a race) a separate branch of master should be made for this. The changes should then be reviewed and cleaned when there is time and then the standard merging procedure should be followed to pull the changes into master.

/////

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.

Basic commands:

70px

ISC Git Cheatsheet

ISC Git Presentation on Drive

Another Git Cheatsheet

Git manual

Another good Git reference

Github video guides

Interactive intro to git 

Git branching tutorial

Git merge conflict resolution

Lynda.com tutorial

{TABS}