diff --git a/docs/build/apple-developer.md b/docs/build/apple-developer.md index a1c3a8c6378..8339133a952 100644 --- a/docs/build/apple-developer.md +++ b/docs/build/apple-developer.md @@ -65,7 +65,7 @@ You can try a free account first before buying a paid developer account. If you The two apps will look identical on your phone and they will both have the name Loop with the same icon, but they will be functionally separate from each other. Make sure you are successful building the PaidLoop app before deleting the FreeLoop app from your phone. Use the search feature on your phone to find both apps. One will have your configuration settings (FreeLoop), the other will not (PaidLoop). -Before deleting the FreeLoop, either record all the settings or take screen shots of all the relevant settings screens. +Before deleting the FreeLoop, either record all the settings or take screenshots of all the relevant settings screens. PaidLoop will know nothing about the settings and information you had stored in FreeLoop, so you will need to re-enter all your settings (basal rates, ISF, carb ratios, etc.) and configurations into the new PaidLoop. It will also not connect or control any pods you are currently using with the old FreeLoop app. The one exception is Nightscout credentials, which are stored in your keychain. If you entered your Nightscout credentials into FreeLoop, they will persist across app removal and be used by PaidLoop. diff --git a/docs/build/build-errors.md b/docs/build/build-errors.md index bbabf28a94e..5fd7b4b1ac5 100644 --- a/docs/build/build-errors.md +++ b/docs/build/build-errors.md @@ -278,7 +278,7 @@ Paste the lines into the terminal. The response to the first line will be someth --w------- 1 marion staff 490 Nov 8 04:58 /Users/marion/Downloads/BuildLoop/LoopConfigOverride.xcconfig -There will be no response after the second line - although if an error is reported, please grab a screen shot. +There will be no response after the second line - although if an error is reported, please grab a screenshot. The response to the last line will be something like this: diff --git a/docs/gh-actions/gh-errors.md b/docs/gh-actions/gh-errors.md index 890e2698c27..0f757e0e7ce 100644 --- a/docs/gh-actions/gh-errors.md +++ b/docs/gh-actions/gh-errors.md @@ -1,26 +1,34 @@ -## *GitHub* Browser Build Errors +## Help with Errors + +If you get an error when building with a browser, use this page to figure out what to do. -This method is fairly new so new errors are being captured as people use this method. Each time a new error is discovered, we try to update *LoopDocs* to make it easier for the next person to succeed without errors. +If you are still unsuccessful, then post your request for help along with your GitHub **username**. Mentors can go to your public GitHub repository, check the status and then view your log files directly. -If you've been around Loop for a while, you know the mantra about screenshots. Well, for *GitHub* Build Action failures, **screenshots are close to useless**. If you get an error with a *GitHub Action*, you should use the search feature for known diagnosis strings. If you are still stuck, then post your request for help along with your **GitHub username**. Mentors can go to your public LoopWorkspace fork - check that your branch is up to date and then view your `GitHub Action` log files directly. +* Do not copy from the log file and post the words +* Do not take a screenshot of what you think is an error +* Just post your username and the name of the app you are trying to build + +!!! tip "Username, Not Pictures" + If you've been around the DIY community for a while, you know the mantra about screenshots. Well, when using a browser to build, **screenshots are close to useless**. But first - try to diagnose it yourself using this page. -## Most Common Mistakes +### Most Common Mistakes These are some of the most common errors to date. -* Make a spelling error when adding Secrets +* Common mistake: you made a spelling error when adding Secrets * Each secret must be spelled exactly the way it is presented in the instructions -* Save your Secrets, as directed, but use a smart editor instead of a text-only editor + * If you are using an automatic translation, please keep an original page open too and copy from it to make sure there are no spelling errors in the secret name +* Common mistake: use a smart editor instead of a text-only editor to save your information * It only takes one letter to be changed from lower-case to upper-case by your smart editor to ruin your day * The alpha-numeric values used for `GH_PAT`, `FASTLANE_ISSUER_ID` and `FASTLANE_KEY` contain both upper and lower-case characters and all the values are case-sensitive -* When entering `TEAMID`, make a spelling error in the value - please copy and paste instead of typing what you think you see - * If you type in your `TEAMID` as `0123498989` when it is really `012349B989`, you may not notice - * Hint: what should have been the letter `B`, got typed as the number `8` - * The incorrect `TEAMID` will show up in your identifiers as the `Bundle ID` but . . . - * You will not be able to `Create Certificates` or `Build Loop` because your `TEAMID` does not match the `Bundle ID` -* Run the actions out of order or skip one +* Common mistake: when saving `TEAMID`, you type what you think you see instead of using copy and paste +* Common mistake: skip running one of the actions + +If you are running development code, skip ahead to [Preview for Version 3.4](#preview-for-version-34). + +The next section is valid for Version 3.2.x and earlier. ## Find Your Error @@ -438,3 +446,36 @@ These steps are needed to reset your `Match-Secrets`: If you add an app to your *GitHub* username (by forking the repository and adding Secrets) and then build it, it encrypts your `Certificate` using `MATCH_PASSWORD`. If you already have the other apps configured and then you delete `Match-Secrets` and add a new one, you will need to run `Create Certificates` for each app before the next time you build each app - go ahead and do that now so you don't forget. + +## Preview for Version 3.4 + +When dev is released as Version 3.4.0, this will be the error finding section in LoopDocs. + +Error annotations are available for Version 3.3.0 and later. These were contributed by community volunteers along with the improvements to enable automatic updates and automatic builds. + +## Examine Annotation + +If a GitHub Action fails, you will see a clear notification. + +First consider the following results from the GitHub Action: 1. Validate Secrets. + +Your screen may look similar to the graphic below. The name in parentheses refers to the branch used to develop these wonderful messages. Yours may be (dev) or (main), once 3.4.0 is released. + +![graphic showing failure to validate secrets](img/error-validate-secrets.png){width="500"} +{align="center"} + +But there are so many reasons why this could happen. The first step is to click on the link highlighted by the red rectangle in the graphic above. This opens a new detailed view. The GIF below shows two different error messages. The first frame shows the error in the Annotation box at the bottom (you may need to scroll down to see this), and you may need to click on "Show More" to see the full message as seen in the second frame. The third frame of the GIF shows a different message. Each one these messages is designed to make it easier for you to diagnose your own problem. + +![graphic showing validate secret error messages](img/error-annotations-validate-secrets.gif){width="800"} +{align="center"} + +Notice that GitHub Action: 1. Validate Secrets is broken into three jobs each of which will either pass and show a green check or fail and show a red check. The secrets are validated with each action, so you will see this a lot. + +For example, the graphic below shows a failure of GitHub Action: 3. Create Certificates . + +![graphic showing failure to create certificates](img/error-create-certs.png){width="800"} +{align="center"} + +This is an example of a message that is not terribly descriptive - which is why it is shown here. In this case, you can click on just the one job that failed. There will be less to sort through to find your error. The most likely reason for this error is [Error: Could not decrypt](#error-could-not-create). + +If you run across an error that does not have a nice message, be sure to post as discussed in [Help with Errors](#help-with-errors). You may be contributing to future improvements for this process. diff --git a/docs/gh-actions/img/error-annotations-validate-secrets.gif b/docs/gh-actions/img/error-annotations-validate-secrets.gif new file mode 100644 index 00000000000..c95d7c578c2 Binary files /dev/null and b/docs/gh-actions/img/error-annotations-validate-secrets.gif differ diff --git a/docs/gh-actions/img/error-create-certs.png b/docs/gh-actions/img/error-create-certs.png new file mode 100644 index 00000000000..2017afda5b8 Binary files /dev/null and b/docs/gh-actions/img/error-create-certs.png differ diff --git a/docs/gh-actions/img/error-validate-secrets.png b/docs/gh-actions/img/error-validate-secrets.png new file mode 100644 index 00000000000..14023e64bda Binary files /dev/null and b/docs/gh-actions/img/error-validate-secrets.png differ diff --git a/docs/loop-3/displays-v3.md b/docs/loop-3/displays-v3.md index 24ea9a36c8a..6e63afcb694 100644 --- a/docs/loop-3/displays-v3.md +++ b/docs/loop-3/displays-v3.md @@ -211,7 +211,7 @@ When you tap on the Loop Icon on the main screen, you will see a message similar * Closed Loop enabled or disabled * How long since the last successful [Loop Cycle](#loop-cycle); <20 minutes, <4 hours, more than 4 hours -On your phone, you should see the green, yellow or red icon in the background - the color is not captured when taking screen shots of the modal message. +On your phone, you should see the green, yellow or red icon in the background - the color is not captured when taking screenshots of the modal message. ![example modal messages seen after tapping the loop icon on the main screen](img/loop-icon-modal-messages.jpg){width="750"} {align="center"} diff --git a/docs/loop-3/settings.md b/docs/loop-3/settings.md index 067af85a9c3..d6fc0e870b6 100644 --- a/docs/loop-3/settings.md +++ b/docs/loop-3/settings.md @@ -163,7 +163,7 @@ Tap on the `Issue Report` row, on the graphic above, to create a Loop Report tex * Issue (on github) is used to report code problems * `Issue Report` is an action in Loop app to provide information you may need when you ask for help: refer to [How to Find Help](../intro/loopdocs-how-to.md#how-to-find-help) -It's a good idea to use the `Issue Report` button and save it along with a screen shot if you think you will ask for help. You can always discard these if you resolve the problem on your own. +It's a good idea to use the `Issue Report` button and save it along with a screenshot if you think you will ask for help. You can always discard these if you resolve the problem on your own. !!! tip "Pro Tip" The Loop Reports can be saved in the Files section on your iPhone. I have a folder on my phone Files named Loop Reports. diff --git a/docs/nightscout/remote-commands.md b/docs/nightscout/remote-commands.md index a32c20d7641..822e124388b 100644 --- a/docs/nightscout/remote-commands.md +++ b/docs/nightscout/remote-commands.md @@ -25,9 +25,9 @@ When you need to configure your authentication method, you can either use a save Options: * Have your Looper (or at least their phone) available -* Save a screen shot of their QR code +* Save a screenshot of their QR code * Keep this secure - * Do not share the QR screen shot when asking for help + * Do not share the QR screenshot when asking for help ![example screen for nightscout and qr code](img/qr-code-example.png ){width="650"} {align="center"} diff --git a/docs/nightscout/remote-errors.md b/docs/nightscout/remote-errors.md index 511c478dfc3..8be55faaec3 100644 --- a/docs/nightscout/remote-errors.md +++ b/docs/nightscout/remote-errors.md @@ -26,7 +26,7 @@ If you attempt to issue a command from  NightscoutLoop Caregiver; after you authenticate the command, you will see the error message listed below and shown in the screen shot. +If you attempt to issue a command using  Loop Caregiver; after you authenticate the command, you will see the error message listed below and shown in the screenshot. ``` HTTP Error diff --git a/docs/operation/loop-settings/configurations.md b/docs/operation/loop-settings/configurations.md index 6ab1116d2e1..6e8b6901283 100644 --- a/docs/operation/loop-settings/configurations.md +++ b/docs/operation/loop-settings/configurations.md @@ -34,7 +34,7 @@ When the Closed Loop switch is in the (On) position, Loop WILL automatically mod If you run into problems or errors with your Loop, a Loop Report, generated by tapping on the `Issue Report` row can be used to help identify where the problem is occurring. The Loop Report can be sent to yourself via text or email. You can then post it on Zulipchat to ask for help. -Frequently, if you seek help with a technical problem, a Loop Report will provide insight for the developers and troubleshooters. Please email yourself a Loop Report anytime you are questioning Loop actions or displays. Acquiring a screen shot of the phone is also useful. You can use the report and graphics later to ask for help or discard them if you figure it out on your own. +Frequently, if you seek help with a technical problem, a Loop Report will provide insight for the developers and troubleshooters. Please email yourself a Loop Report anytime you are questioning Loop actions or displays. Acquiring a screenshot of the phone is also useful. You can use the report and graphics later to ask for help or discard them if you figure it out on your own. ## Select Glucose Units diff --git a/docs/version/overview-version.md b/docs/version/overview-version.md index cd033699d6b..0aa0fb111c4 100644 --- a/docs/version/overview-version.md +++ b/docs/version/overview-version.md @@ -10,8 +10,8 @@ Map to this section: * [Code Customization](../build/code-customization.md) - Instructions for customizing your DIY code - Think of this as your personalized version -* [Customize with GitHub](../gh-actions/gh-customize.md) - - Instructions for customizing using just a browser +* [Customize with Browser](../gh-actions/gh-customize.md) + - Instructions for customizing using a browser * [Simulator Build](simulator.md) - Instructions for building to a simulator * [Loop Development](../version/development.md) diff --git a/mkdocs.yml b/mkdocs.yml index 501c86bbe21..5f39b6e480a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -131,7 +131,7 @@ nav: - 'Test Settings': 'build/test-settings.md' - 'Loop Data': 'build/loop-data.md' - 'Meet the Community': 'build/community.md' -- Browser Build: +- Build with Browser: - 'Build with Browser Overview': gh-actions/gh-overview.md - 'Configure to use Browser': gh-actions/gh-first-time.md - 'Install on Phone': gh-actions/gh-deploy.md