Git Workflow and Actions
Last updated
Last updated
The Head Tracker GitHub page is setup for continuous integration (CI) what this means is every time a change in the code is made to it will compile the result with binary files you can run. This allows anyone to easily download and test recent changes without having to setup the full development environment.
The standard way to make a change or addition to the code is for a user to make a fork of the project. A fork is a copy of the base repository that you can modify. After making a fork you are going to create a new branch. You can name this branch something suiting to the change you are planning on creating.
You can create as many branches in your fork as you want if your testing out various ideas or working on multiple ideas at a time.
When you have a branch you want to add to the main project you will then do a Pull request. When you make a pull request, put a short description of the changes in the comments. A maintainer will review the changes, comment may request changes and finally will approve and merge them into the project.
All of the current pull requests from Users will be shown here
As soon as you start a Pull request GitHub Actions will start compiling the code changes. Depending on the code that was changed one or more workflows will trigger.
You will be greeted with a window that looks like this.
On the left, there are 4 workflows. You can filter the results by clicking these individual items.
Firmware Build - This builds the firmware that will be written to the Nano and other supported boards
Linux GUI
MacOS GUI
Windows GUI
- These are the configuration GUI's for all the supported operating systems.
On the right side of the screen is each workflow that has run. Below is an example created by user gcmcnutt in their branch named SerialUpdate. The green check mark means is successfully compiled. This workflow compiled the Firmware.
The main code tree that will eventually become the next release is in a branch called master. Below shows an example of an workflow that ran on the master branch. After a pull request is approved it will be merged into this master branch. This workflow compiled the Windows GUI
When a workflow completes successfully (Green Check Mark) it creates artifacts. In the case of the workflows in Head Tracker the artifacts are either the GUI or the Firmware.
Click a workflow to see it's details. Here you can see the process of it building and potentially where it has failed. On successful builds you will see artifacts at the bottom of the page.
In the above example for an action that compiled the Windows GUI there is one artifact called headtracker_win. Clicking this will download the GUI so it can be tested.
You must be logged into GitHub to download actions. Otherwise clicking the action will do nothing. GitHub accounts are free.
If you were are looking to test out the most recent build you will need to search the list for the newest actions that ran on master and will need one GUI that matches your operating system and one firmware.
Download and extract both .zip files to a location on your PC.
When you open the GUI you will need to flash this downloaded firmware. Choose Firmware -> Upload Firmware. You won't be greeted with any available release firmware choices, only local file.
Using the browse, the three dots navigate to where you extracted these files and choose the firmware that matches the board you own. As of this writing there are two choices.
After flashing the Firmware, you can test out the current state of the code.
Running these development builds there may be issues. Please help out by reporting any issues found including comments. Create an issue on the Github Issues page or contact a developer on Discord in the #dev chat room.
Be sure to make a note of the SHA on your issue, which can be found after clicking the action. Highlighted in yellow below. This is a unique identifier for that particular state of code.
