Custom Edits with Browser

Hot Topics

Pro Tip

The method on this page allows you to create a set of personalized customizations that you can use in addition to the Loop and Learn: Prepared Customizations. You can use (and re-use) your customizations with either Browser Build or Mac builds so you don't have to repeat the customization with every update.

• If you are building with Mac method, you can use the same lines prepared for Build with Browser method and simply paste them in your terminal at the LoopWorkspace folder to customize your code
• You can often use the same customization for several releases
• If a customization that you prepared for an older release says "does not apply" when you use it, you'll need to prepare a new one

Modules vs Submodule

This page has instructions to set up your own fork for the Modules, otherwise known as submodules, associated with LoopWorkspace that are needed for a selected customization.

Each Module has its own GitHub repository; and you will be working with your fork of that Module at https://github.com/my-name-org/Module, where you use your own organization (recommended) or personal account.

If you are an experienced builder who set the Submodule changes up in your personal GitHub account, you can leave those forks where they are, i.e., https://github.com/my-name/Module. You do not build from Submodules, so no Secrets are required.

What is a SHA-1?

SHA-1 means Secure Hash Algorithm 1; which is used to generate an alphanumeric code.

Each time you save a change to your GitHub repository, a unique SHA-1 is created. That identifier is used to tell GitHub a specific change that you want applied or identifies a specific version for that repository. These work for any compatible fork from the original GitHub repository.

Do Not Make a Pull Request to LoopKit GitHub Username

Ignore Compare & pull request Prompts

Please do not click on boxes that GitHub might show you that ask if you want to Compare & pull request.

This would be an attempt to merge changes from your fork back to the original version that everyone uses. These changes are for you only. Ignore those prompts.

Of course, accidents happen. No worries.

• Just hit the Close button
• If you don't close the accidental PR yourself, it will be closed for you, but that takes time from the Loop developers

Overview

Time Estimate

• About half an hour to an hour per Module
  • Typically 1 or 2 Modules
• Ten minutes to add patch lines to your build_loop_auto.yml file
• One minute to start the build
• An hour before the build shows up on your phone in TestFlight

Summary

• Prepare Customization (One Time):
  • Once you have prepared a given customization, you can use it again with every build and even across most updates
  • If there is an update (new release) and the customization is no longer valid - you will get a clear error message
    • Just follow the steps on this page again to replace the customization that did not work
  • If there is an update (new release) and the customization applies with no errors, then you do NOT need to create an update
  • It is a good idea to test each customization as soon as you install the new build on your phone
• LoopDocs: Decide on Modules to modify using the Version: Custom Edits page
  • You only need to create your own customization if what you want is not provided at Loop and Learn: Customization List
  • If there are customization not provided by the Customization List, then you need to make personalized edits
  • This current page explains how to make the edits using a browser
  • The Version: Custom Edits gives instructions on identifying the Module, finding the file and editing the line(s)
• GitHub (each Module):
  1. Fork the Module (if needed) - this is your fork where you will make changes
  2. Sync the Module (if needed)
  3. Make the desired modification(s) using the pencil tool
  4. Save your changes to a patch branch
  5. Prepare lines needed for each customization and save
• With Loop 3.4 and newer, there are 2 ways to add customizations (use only one)
  • See Update LoopWorkspace
  • See How to use the patches Folder
• Regardless of the method, incorporate the customization with Action 4: Build Loop
• (Optional): Add Test Details to TestFlight
• Phone: Install with TestFlight

FAQs

• Do I need a Mac computer? No. This can be done on any browser.
• Should I build without customizations first? Yes. Make sure the build process works without customizations. You don't need to install the build on your phone, just make sure it builds without errors before you start modifying.

How to Customize Build with Browser

You do this using any browser on a computer or laptop. (Phone is not recommended - screen is too small.)

There is some background information at the bottom of this page starting at LoopWorkspace if you want to know what you are doing. Otherwise, just follow the steps like a cookbook.

Decide Which Modules You Want to Modify

Decide which Version: Custom Edits changes you want to make. Each customization lists a Module name.

• Any Pod Type: Use OmnipodKit which is hosted at the loopandlearn GitHub username
  • When you change Pod Types, this customization remains in place
• Other Modules are Loop and LoopKit
  • Do not get confused later: LoopKit is both a username and a Module name
  • Refer to the Module Table when directed

For versions 3.4.x, the customizations for main and dev are the same.

When moving from v3.4 to v3.6, several items that used to require customization are no longer needed. They are included in v3.6.

For versions 3.6.x and newer, the customizations for main and dev are the same.

For versions 3.14.2 and newer:

• the old OmniBLE (DASH) and OmniKit (Eros) repositories are no longer used
• the new OmnipodKit (Eros, DASH and Omnipod 5) repository is used for all Omnipod support

Outline of What Happens in the Module

Review Only

Review this section so you know what to expect. The actual steps will come later, starting with Create your Fork for Selected Module or Personalized Customization for this Module.

Feel free to skip ahead if you think you don't need the summary.

In the next sections, the exact process for making changes will be documented. But the steps may feel confusing. There are no links here because you are supposed to review the steps before taking action in the next section.

1. First time for this module:
   • Make a fork
2. Change the line(s) of code desired for your customization(s) in your fork
3. Save the change(s) using descriptive comments
4. Repeat until done with this Module

Later, you will use information from your fork to create your customizations. (Suggestion - use same file as your Secrets, or at least keep the customization file in the same folder). Details are found at the Prepare the Customizations section.

Error Committing Your Changes

What should you do if you see the message:

• There was an error committing your changes: File could not be edited

This is fairly rare, but it can happen. A user got this error when editing a file using GitHub:

The solution was to make sure the email address in their GitHub profile was correct. See GitHub Discussions for more information.

Create your Fork for Selected Module

Choose your link:

• New Fork: if you do not have a fork of this Module
• Code Updates: if you are returning after a new release and the customization you used before no longer works
• Existing Fork for Module: if you have a fork but need guidance on whether it is the right fork

Code Updates

New Release

If you have previously used this process for a prior release, use the same Modules you already copied.

You can often reuse customizations that you created earlier even with a new release. Attempt to use your existing patches before creating new ones.

If a customization did not work, then

1. Go to your fork of each Module
2. Make sure you are on the Default Branch for that Module
3. Sync that Module to get the most recent version

Skip ahead to Personalized Customization for this Module.

New Fork

If you want a modification that uses a particular Module, you must make a fork of that module to your account in GitHub. You will repeat the Fork and Modify steps for each module.

1. Log into your GitHub account
2. Click the URL in the Module Table
3. This opens a new browser tab at the URL of the module you need to fork
4. Click on Fork, your fork will show up in the browser

Module Table

This table lists all the modules referred to on the Code Customization page linked above:

Module	Fork From
Loop	https://github.com/LoopKit/Loop
LoopKit	https://github.com/LoopKit/LoopKit
OmnipodKit	https://github.com/loopandlearn/OmnipodKit

Remember - you can only have a single fork of a given GitHub repository. If you already have a fork, you don't need another one; but it must be a linked to the URL listed the Module Table.

I already have a fork

Go to Existing Fork for Module and follow the directions.

Default Table

When you "fork a repository", the default branch is the one that should be forked.

username/Repository	Default
LoopKit/Loop	dev
LoopKit/LoopKit	dev
loopandlearn/OmnipodKit	dev

Personalized Customization for this Module

Navigate to the file you need to modify (using the instructions to find the lines from the Version: Custom Edit page).

How do I navigate to the file? (Click to open/close)

Let's do an example.

Suppose you want to add this customization: Pods: Add Extra Insulin on Insertion

The folder name is: OmnipodKit/OmnipodKit/OmnipodCommon
The file name is: Pod.swift

So you will go to your OmnipodKit fork (see New Fork if you don't have a fork yet).

Ensure your fork is up-to-date. Tap on the Sync fork button if necessary.

1. Tap to select OmnipodKit folder in that fork
2. Tap to select OmnipodCommon folder in that folder
3. Tap to open the Pod.swift file
   • Once the file is open, tap on the pencil icon and make your edits
   • When done, review the Example GIF which shows the steps needed to save your changes after you complete the edit

The graphic below shows the fork for the OmnipodKit submodule with numbers that match the steps in the list above. If you need more detailed instructions, they are found after the graphic.

More detailed instructions (Click to open/close)

1. Check that this repository is the correct submodule and that:
   • Fork has your GitHub Username
   • Fork says it is forked from loopandlearn (or LoopKit for other repositories)
   • Fork is up to date with loopandlearn
   • Tap on the OmnipodKit folder to open the next screen
2. Check that your screen shows:
   • OmnipodKit/OmnipodKit at the top (current folder location)
   • Tap on the OmnipodCommon folder to open the next screen
3. Check that your screen shows:
   • OmnipodKit/OmnipodKit/OmnipodCommon at the top (current folder location)
   • Tap on the Pod.swift file to open it
   • Tap on the pencil icon (upper right) to start editing the file

Now you are ready to move to the Example GIF which shows the steps needed to save your changes after you complete the edit.

Pro Tip

Look at the files you want to change - if more than one change is desired for a single file - do them at the same time.

This section provides the steps to make a single customization for the Module. If you need more than one, just repeat the process and make additional ""patch" branches.

Example GIF

The GIF below shows the steps needed to save an edited file, so you can configure the customization. Please review the 4 frames of the GIF, read the Detailed Instructions below and then review the GIF again.

There are 4 frames shown in this GIF; the frame number is noted at the bottom right. Take the time to cycle through several times to observe what you need to do.

• Frame 1 shows what to do after you have completed the edits you want for this file

• Frame 2 shows a Pull Request to your own repository - that is OK

• Frame 3 displays a green Compare & pull request button that would make a Pull Request to a LoopKit/repository - do NOT click that button

• Frame 4 shows how to obtain the really-long alphanumeric string (SHA-1) needed to modify your build_loop_auto.yml file

Detailed Instructions

If you followed along above and made the modifations, you can skip ahead to Prepare the Customizations.

This section provides the detailed steps just explained in Example GIF.

You will be using the "pencil" tool in the browser display for your fork.

Are there detailed instructions?

For more information about editing with GitHub:

• GitHub Docs: Editing Files

The bullets below go with Frame 1 of the GIF above:

• Once you make the change to a given file, click on "Commit changes" (upper right)
• Click in the "Commit message" box and replace the default "Update filename" with a comment about what the customization does
• Click on the second option near the bottom "Create a new branch for this commit"
  • Note: when you do the LoopWorkspace modifications, you will not choose this option
• Click on the "Propose changes" button
• As soon as you do this, a new "branch" is automatically created with a name like username-patch-#, where the number increments each time

The bullets below go with Frame 2 of the GIF above:

• You will be shown a screen where you create a pull request to your own fork (this does not go back to the original)
• First review the changes (shown at the bottom) and then click on the "Create pull request" button

Between Frame 2 and 3 of the GIF, your display will look similar to the graphic below

• This is an old figure - if you are making Pod edits, you will see OmnipodKit - not OmniBLE

You see there an opportunity to "Compare & pull request"

• Do not click on that
  • This would be an attempt to merge changes from your fork back to the original

The branches selection is highlighted with a brown rectangle in the graphic above.

• You can use the drop-down menu or click on the word branches.
• Choose the branch you just created, i.e., username-patch-#.

Your screen should now look like Frame 3 of the GIF above:

• Click on the Clock icon to the right

Now your display should look like Frame 4 of the GIF above:

• The top line is the last thing saved (your customization)
• You need to record the very long alphanumeric number associated with this
• There is a copy icon to the right - click on it and save it in your text file along with a comment about the customization and record which module you used for the customization

For example:

# OmnipodKit: Increase insulin at insert by 0.35 U
SHA-1 = 5e9f4f407ff5544663f496d2e3a5ed8aa4f32a68

Warning - that is not a valid SHA-1 for this change. Do not try to copy it and use it. You must make your own personalized changes.

Later on, you will create the actual command needed to insert into build_loop_auto.yml so you can add this customization when your build the app.

Repeat this process until you've done all your customizations for this Module and then move on to the next Module.

Prepare the Customizations

There are two ways to use this customization. Keep reading for the method in which you edit the build_loop_auto.yml file. If you are feeling adventurous, check out How to use the patches Folder.

Once you prepare the commands, then you will edit the build_loop_auto.yml file of your fork of LoopWorkspace.

Ensure your fork is from LoopKit/LoopWorkspace

If your LoopWorkspace fork did not come from LoopKit/LoopWorkspace, then delete your existing fork and make a new one. See Already Have LoopWorkspace?.

• Do not use any other location to create your fork

For each customization you want to include, create a pair of lines consisting of the comment (must start with a #) followed by the curl statement pointing to the SHA-1 that has the customization.

Prepare customization lines

Save the customization lines in your text file for later use in the build_loop_auto.yml file.

Customization Template:

# Module: File: code customization description
curl https://github.com/my-name-org/Module/commit/SHA-1.patch | git apply -v --directory=Module

where:

• curl means copy from URL
• username is your GitHub username
• Module is where you made the customization (Module is in multiple places)
• SHA-1 is the full identifier for the desired change; there is a copy button to make this easy
• adding .patch after the SHA-1 informs GitHub to format that code change so it can be applied to your fork
• the final  --directory=Module is critical to apply the customization to the correct Module

To view the exact code change associated with that patch, open a browser at the URL of https://github.com/my-name-org/Module/commit/SHA-1.

Update LoopWorkspace

With the release of 3.4.x, there are two ways to use this customization. Keep reading for the method in which you edit the build_loop_auto.yml file. If you are feeling adventurous, check out How to use the patches Folder.

The final step is to update your LoopWorkspace fork to apply these customizations by adding those customization lines into the build_loop_auto.yml file.

Return to your GitHub fork for LoopWorkspace and make sure to sync it if needed.

• Find the folder .github/workflows and click on it
• Find the file build_loop_auto.yml and click on it
• Click on the pencil (so you can edit this file)

Add Personal Customizations to build_loop_auto.yml

Open the text file in which you saved the customization lines.

For a given submodule, paste the "comment" and "curl" lines that you prepared in Prepare customization lines (similar to the examples found in lines 279 through 286). These examples are commented out and are just for guidance. The best place to paste these is at the end of the # Customize Loop: Download and apply patches section and before the # Patch Fastlane Match to not print tables line.

The indenting needs to match, so tab or (shift-tab) to line up the columns. The graphic below shows a couple of common mistakes.

• All lines within a given section need to start in the same column (see the vertical dashed green line)
• Comments (lines starting with a #) placed in the wrong column will cause the build to fail
• Commands (line starting with curl) placed in the wrong column will cause the build to fail

The command placed in the correct column has 4 "words" highlighted with red rectangles. You must have the correct values for all 4 of these places or the build will fail.

It is best to leave a blank line between customizations.

You must have a blank line after the last customization and before the # Patch Fastlane Match to not print tables line or the build will fail.

Once you are done with all the edits for build_loop_auto.yml you will commit the changes to your fork directly.

• Once you have finished the edits for build_loop_auto.yml
• Click on Commit changes (upper right)
• Click in the larger box below "Update build_loop_auto.yml" and summarize the customizations you added
• Click on the option to "Commit directly to your branch"
  • NOTE: for LoopWorkspace fork - commit directly to your default branch
• Click on Commit changes
• You can make as many changes to build_loop_auto.yml in your fork as you want

When you are ready, it's time to build with your customizations.

Build with Customizations

At the top of the display, click on Actions.

• Click on Action 4: Build Loop
  • Click on Run workflow on the right side
  • Then click on the green Run Workflow button

Wait about 2 minutes before walking away to make sure there are no errors. If you get an error, then look for the first "did not apply" error message and fix the customization right before that line.

In about 1 hour, your customized app will be available for installation on your phone via TestFlight.

Extra Information

The rest of this page has additional information most people can skip.

How to Use the patches Folder

With Loop 3.4.0 and newer, you can add patches to your GitHub-Username/LoopWorkspace fork in the patches folder. Those patches will then be automatically added to your build every time without needing to modify the build_loop_auto.yml file.

Refer to Prepare customization lines:

• extract the text from "https:" through "patch" and paste that into a new tab
• this will open a browser similar to the following graphic
  • this graphic was prepared using the old OmniBLE repository - now the patch would be with OmnipodKit

Now you need to download that file (Save Page As, if using chrome).

Once the file is downloaded to a sensible name, make a copy (or rename it) to indicate that you have edited the file to make it a Workspace level patch. An example is shown below.

• Top file shows the original download
• Lower file shows the renamed and edited version:
  • Add the name of the module to the "a" and "b" directory paths so the patch is applied to the correct folder (from LoopWorkspace)
  • In this example OmniBLE/ was added in 4 places as highlighted by red rectangles
    • WARNING: this graphic is old - a new one would use OmnipodKit, OmniBLE is no longer used

If you've gotten this far, keep going. No more pretty graphics, but I think you can figure it out.

• Return to your GitHub-Username/LoopWorkspace fork, tap on the patches folder
• At the upper right, click on Add file dropdown and choose Upload files
  • Drag and drop your Workspace level patch into the window
  • Commit to your default branch
• Test the build to make sure everything worked

Special Cases

Existing Fork for Module

What if you already have a fork of one of the modules?

Your existing fork is from a username other than LoopKit

• If you know this is a fork you do not care about, you can delete the repository.
• If you care about this fork, you are probably experienced enough to know how to solve the issue.

Instructions to delete a repository are found at GitHub Docs

Once deleted, go to Create Your Fork for Selected Module.

Background Information

LoopWorkspace

The LoopWorkspace repository is the umbrella organization holding all the pieces needed to build the Loop app. It provides a list of pointers to a specific version for each of the Modules used in the workspace.

• commit: a specific change to the code identified by the SHA-1; the most recent one indicates the most recent version of the code
• workspace: a grouping of several repositories (Modules) into a complete package
• LoopWorkspace: includes a list of the specific SHA-1 for each Module needed for the app

You are telling GitHub to apply specific customizations when it builds your app for you. It extracts from GitHub all the code needed, applies your specific customizations and then starts the build.