| You are not Logged In! |
Difference between revisions of "Public:GitHub/b-fw"
(Created page with "Hi") |
m (Adityaj5 moved page GitHub/b-fw to Public:GitHub/b-fw) |
||
| (7 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
| − | + | {{Infobox GitHub Repo|org=IlliniSolarCar|repo=b-fw|status=Active|forkOrg=|forkRepo=|defaultBranch=master|access=Private|license=All Rights Reserved to ISC|branching=Git Flow|maintainer=Electrical Group|checks=* Reviews Required for Master | |
| + | * Auto Labels | ||
| + | * Include Guard Checking | ||
| + | * Submodule Checking|content=Firmware for Electronics on Brizo}} | ||
| + | |||
| + | {{GithubRepo|org=IlliniSolarCar|repo=b-fw}} if the repo for [[Firmware Standards|firmware]] on Brizo - the repo was created before the car had a name. Unlike other repos, we currently maintain one repo for firmware for each vehicle (see {{GithubRepo|org=IlliniSolarCar|repo=ARGO-FW}}). Typically the team will have multiple operational cars that might need firmware maintenance, and the changes from car to car are breaking - necessitating keeping them both separate. | ||
| + | |||
| + | This repository has two submodules - [[GitHub/mbed]] and [[GitHub/CAN]]. Mbed is the operating system and is a fork, while CAN is a shared repo with the Telemetry group to keep the CAN specifications up to date between the vehicle firmware and telemetry application ([[GitHub/Telemetry]]) | ||
| + | |||
| + | == Workflow == | ||
| + | The firmware repo is a highly collaborative repo. C++ is pretty much exactly the use case git was designed for so it is a very standard git repo in that case. Many people will be working on many things at once. Some people on the same branch, some on different. Some branches will be short lived, some will be long lived. While this may sound chaotic, there is order to the chaos. | ||
| + | |||
| + | === Branch Organization === | ||
| + | [[File:GitFlowHotfixBranch.png|thumb|The Firmware repos use the common "Git Flow" structure. ]] | ||
| + | This repo will have a lot of branches. To manage these branches we use the "Git Flow" structure for these branches. There will be some long-lived branches and some short-lived branches based on what they are for. To the right is an example of how Git Flow is structured. Below we'll explain each of the different branch types in terms of this repo and solar car. | ||
| + | |||
| + | ==== Master Branch ==== | ||
| + | Stable code for the car lives here. This code has all been significantly tested and should be reliable. If a competition happened tomorrow we would be confident in this code to work well. All code for competition will be on master before hand. | ||
| + | |||
| + | ==== Hot Fix Branches ==== | ||
| + | A hot fix branch is for a small fix to the master branch code. These include things like tuning, tweaks, or covering missed edge cases. This is ''not'' where significant architecture changes are made. If a major feature is having issues it should be removed from master and resume being worked on on its feature branch - not hot fixed. However, all changes at competition are hot fixes. | ||
| + | |||
| + | ==== Release Branch(es) ==== | ||
| + | This is code that is ready to be tested on the whole bench system and eventually (potentially) the solar car. Once it is stable on the bench the "release candidate" can be tested on the car and, if passed, proposed to master. At this point has also gone through a full code review. There may be multiple release branches to work on things in isolation, but we need to be careful that things in parallel do get tested together before they both make it to master. | ||
| + | |||
| + | If you need the most recent stable code for testing bench code this is the place to go. | ||
| + | |||
| + | ==== Development Branches ==== | ||
| + | There is a development branch for each board on the car. This is where code from different features on that board are combined and tested on the bench. These branches will regularly, when there is a stable tested version, be code reviewed and pull requested into a release branch for car testing. | ||
| + | |||
| + | ==== Feature Branches ==== | ||
| + | Each feature of each board will have a branch for it to be worked on. This code will be tested in isolation and then reviewed/pull requested into the development branch for that board where it is ready for system testing. Usually, a feature should already be outlined on the development branch before it is created on a feature branch so that we can avoid architecture conflicts. | ||
| + | |||
| + | Feature branches are created from Development branches. | ||
| + | |||
| + | === Repo Structure === | ||
| + | The repo structure is divided up in to several folders. All projects have their own folder and use the shared <code>common</code> and <code>mbed</code> folders. The folders are: | ||
| + | * <code>common</code> - shared common code for all boards such as shared drivers and the CAN submodule | ||
| + | * <code>mbed</code> - submoduled folder of our MBed operating system fork | ||
| + | * <code>mbed15x9_skeleton</code> - skeleton project for creating a new one | ||
| + | * <code>wheel</code> - code for the [[Brizo:Steering Wheel|steering wheel]] | ||
| + | * ... | ||
| + | |||
| + | === Starting a Project === | ||
| + | Projects are made from the template project. There is one project per board, so making new projects does not happen very often. See [[MCUXpresso]] for instructions on cloning the MCUXpresso project. | ||
| + | |||
| + | === Making Changes === | ||
| + | Most of the code will be written on feature branches while bug fixes, optimizations, and improvements can happen anywhere along the process as they are identified. Keeping your individual branches as small of scope as reasonable is a good way to keep an organized process. Your work should be captured as [https://github.com/illinisolarcar/b-fw/issues issues on GitHub] where they can be discussed and hashed out ''before'' you write the code (as well as future to-dos kept track of) and then referenced in a Pull Request. See also [[GitHub Projects]] | ||
| + | |||
| + | === Pull Requests === | ||
| + | Your code will go through several layers of pull reqests before it makes it to master. There should be pull requests for feature->development, development->release, and release->master. At each stage code quality is important. The first PR especially focuses on code quality and architecture while later ones serve as checks on what testing is done and keeping features organized. | ||
| + | |||
| + | === Github Checks / Actions === | ||
| + | |||
| + | ==== Labeler ==== | ||
| + | The b-fw repo also has auto-labeling of pull requests. Specifically to note when there are changes to common, the skeleton, or github files. | ||
| + | |||
| + | ==== Include Guards Check ==== | ||
| + | This checks that every header file has an include guard in it that matches the requirement. This prevents conflicts in the include guards (as two files can't be in the same place) and keeps them consistent. Include guards should be as follows: | ||
| + | * Common: <code>COMMON_{last_dir}_{file_name}_H_</code> such as <code>COMMON_API_CAN_BUFFER_H_</code> | ||
| + | * Project: <code>{project_dir_name}_{file_name}_H_</code> such as <code>WHEEL_PERIPHERALS_H_</code> | ||
| + | |||
| + | '''Submodule Check''' | ||
| + | |||
| + | This check verifies that the mbed and CAN submodules progress as required (to a same/newer version) and are on the right branch. | ||
| + | |||
| + | == Initial Setup == | ||
| + | In order to get the code onto your computer, use <code>git clone --recursive <repo> <optional></code>. The <code>--recursive</code> 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 <code>git submodule update --init</code> to find any un-cloned submodules and clone them. | ||
| + | |||
| + | The submodules in this repo are our fork of Mbed and the [[CAN bus|CAN]] repo. Typically you will not need to change mbed and should work with the submodule on master. You will have to work with the CAN repo whenever adding or changing the messages sent on the CAN bus. | ||
| + | |||
| + | 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 work on code. | ||
| + | |||
| + | To open code on another branch, such as a work in progress or a new feature that needs more testing, checkout the branch using <code>git checkout <branch> --recurse-submodules</code>. If you forget the submodule option, use <code>git submodule update</code> to get the correct version of mbed. | ||
Latest revision as of 23:27, 10 September 2021
 IlliniSolarCar/b-fw
Active | |
|---|---|
| ReadMe | |
| Content: | Firmware for Electronics on Brizo |
| Access: | Private |
| License: | All Rights Reserved to ISC |
| Branching Strategy: | Git Flow |
| Maintained By: | Electrical Group |
| Actions & Checks: |
|
|
View All ISC Repos
| |
IlliniSolarCar/b-fw if the repo for firmware on Brizo - the repo was created before the car had a name. Unlike other repos, we currently maintain one repo for firmware for each vehicle (see IlliniSolarCar/ARGO-FW). Typically the team will have multiple operational cars that might need firmware maintenance, and the changes from car to car are breaking - necessitating keeping them both separate.
This repository has two submodules - GitHub/mbed and GitHub/CAN. Mbed is the operating system and is a fork, while CAN is a shared repo with the Telemetry group to keep the CAN specifications up to date between the vehicle firmware and telemetry application (GitHub/Telemetry)
Workflow
The firmware repo is a highly collaborative repo. C++ is pretty much exactly the use case git was designed for so it is a very standard git repo in that case. Many people will be working on many things at once. Some people on the same branch, some on different. Some branches will be short lived, some will be long lived. While this may sound chaotic, there is order to the chaos.
Branch Organization
This repo will have a lot of branches. To manage these branches we use the "Git Flow" structure for these branches. There will be some long-lived branches and some short-lived branches based on what they are for. To the right is an example of how Git Flow is structured. Below we'll explain each of the different branch types in terms of this repo and solar car.
Master Branch
Stable code for the car lives here. This code has all been significantly tested and should be reliable. If a competition happened tomorrow we would be confident in this code to work well. All code for competition will be on master before hand.
Hot Fix Branches
A hot fix branch is for a small fix to the master branch code. These include things like tuning, tweaks, or covering missed edge cases. This is not where significant architecture changes are made. If a major feature is having issues it should be removed from master and resume being worked on on its feature branch - not hot fixed. However, all changes at competition are hot fixes.
Release Branch(es)
This is code that is ready to be tested on the whole bench system and eventually (potentially) the solar car. Once it is stable on the bench the "release candidate" can be tested on the car and, if passed, proposed to master. At this point has also gone through a full code review. There may be multiple release branches to work on things in isolation, but we need to be careful that things in parallel do get tested together before they both make it to master.
If you need the most recent stable code for testing bench code this is the place to go.
Development Branches
There is a development branch for each board on the car. This is where code from different features on that board are combined and tested on the bench. These branches will regularly, when there is a stable tested version, be code reviewed and pull requested into a release branch for car testing.
Feature Branches
Each feature of each board will have a branch for it to be worked on. This code will be tested in isolation and then reviewed/pull requested into the development branch for that board where it is ready for system testing. Usually, a feature should already be outlined on the development branch before it is created on a feature branch so that we can avoid architecture conflicts.
Feature branches are created from Development branches.
Repo Structure
The repo structure is divided up in to several folders. All projects have their own folder and use the shared common and mbed folders. The folders are:
common- shared common code for all boards such as shared drivers and the CAN submodulembed- submoduled folder of our MBed operating system forkmbed15x9_skeleton- skeleton project for creating a new onewheel- code for the steering wheel- ...
Starting a Project
Projects are made from the template project. There is one project per board, so making new projects does not happen very often. See MCUXpresso for instructions on cloning the MCUXpresso project.
Making Changes
Most of the code will be written on feature branches while bug fixes, optimizations, and improvements can happen anywhere along the process as they are identified. Keeping your individual branches as small of scope as reasonable is a good way to keep an organized process. Your work should be captured as issues on GitHub where they can be discussed and hashed out before you write the code (as well as future to-dos kept track of) and then referenced in a Pull Request. See also GitHub Projects
Pull Requests
Your code will go through several layers of pull reqests before it makes it to master. There should be pull requests for feature->development, development->release, and release->master. At each stage code quality is important. The first PR especially focuses on code quality and architecture while later ones serve as checks on what testing is done and keeping features organized.
Github Checks / Actions
Labeler
The b-fw repo also has auto-labeling of pull requests. Specifically to note when there are changes to common, the skeleton, or github files.
Include Guards Check
This checks that every header file has an include guard in it that matches the requirement. This prevents conflicts in the include guards (as two files can't be in the same place) and keeps them consistent. Include guards should be as follows:
- Common:
COMMON_{last_dir}_{file_name}_H_such asCOMMON_API_CAN_BUFFER_H_ - Project:
{project_dir_name}_{file_name}_H_such asWHEEL_PERIPHERALS_H_
Submodule Check
This check verifies that the mbed and CAN submodules progress as required (to a same/newer version) and are on the right branch.
Initial Setup
In order to get the code onto your computer, use git clone --recursive <repo> <optional>. The --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 --init to find any un-cloned submodules and clone them.
The submodules in this repo are our fork of Mbed and the CAN repo. Typically you will not need to change mbed and should work with the submodule on master. You will have to work with the CAN repo whenever adding or changing the messages sent on the CAN bus.
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 work on code.
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.