Starting Loop: Terminology
What is a Branch? What is a Fork? What the Heck is Github?
There is a lot of new terminology introduced when you come into the DIY community. This page is an attempt to simplify some of the concepts.
The long technical answer to these question is in the LoopDocs Branch FAQ. It is a good read with a fresh box of wine in front of the fireplace when the snow outside is all the way to the top of the windows.
The abridged answer is RIGHT HERE in this document!
The open-source community is a bunch of open-hearted software developers who make some of their code publicly available on the website https://www.github.com
That’s all you need to know. You will be given the addresses you need to know to access the code. However, for Loop (or FreeAPS) and for Nightscout, there are directions to follow that hide some of this from you – you just follow directions and click on links.
When a developer is working on code, the main “branch” is always called master. When they want to fix bugs or add new features, they will make a copy of the code and give it a new “branch” name. At the current time, the master branch and automatic-bolus branch on the main Loop site on github are the stable branches. The other branch you will see linked in the LoopDocs Build page, is called dev and is for experienced Loopers who want to test the next version of Loop and provide feedback to the developers. It is not a good idea for someone just starting out on Loop to use the dev branch. There will also be other branches from time-to-time that are like a sandbox where the developers are trying things out or testing bug fixes. DO NOT TRY those branches – even if they sound like something interesting.
With open-source software, a developer can decide to make a complete copy (fork) of the code and put it on their own github site. They then have the freedom to make their own customizations and add features. One of the forks that is discussed on the Loop and Learn website is the FreeAPS fork. See the Compare Versions page to understand the differences between master, automatic-bolus, and FreeAPS. Before selecting FreeAPS, please review this summary of FreeAPS. This adds a few more terms to your terminology overload. Once again, a top-level definition is all you need. If you’re interested in more, there’s a lot of information out there on the internet.
To clone is to make a fork for yourself and save it on your website or your personal computer. If you follow the Build-Select script directions, in the background, the script will clone the workspace version of the selected Loop code to the Download folder on your Mac or Virtual Machine.
Loop isn’t just one set of code from one repository. It actually uses code from multiple repositories. If you follow the links to download code using the LoopDocs Step 13 document, you’ll be getting a zip file of the code from LoopKit/Loop along with a list of other repositories that Xcode will use to retrieve code while building Loop. But there’s another way to gather all the needed pieces and parts.
If instead of using the link to the zip file from LoopDocs, you can use a “workspace build.” A workspace build allows you to clone (copy) all the code from various repositories to your local computer. The code from each repository will show up as folders in your Xcode display. The easiest way to build Loop actually turns out to be a workspace build using a nifty Build-Select script. It’s fast and easy. Plus, there are some code customizations that can only be done using a workspace build.
We promised you don’t need to be a computer programmer to Loop. You do not need to understand all this terminology. But you may see some of these terms; if you do, just keep on going. There will be pictures and numbered steps, and mentors willing to assist.