Merge pull request #729 from marionbarker/working-docs

Browser Errors: document new messages

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.
 

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:
 

docs/gh-actions/gh-errors.md

@@ -1,26 +1,34 @@
-## <code>*GitHub* Browser Build</code> 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&nbsp;<span translate="no">GitHub</span>&nbsp;**username**. Mentors can go to your public&nbsp;<span translate="no">GitHub repository</span>, 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 <code>LoopWorkspace</code> 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 <code>Secrets</code>) 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&nbsp;<span translate="no">GitHub Action</span>&nbsp;fails, you will see a clear notification.
+
+First consider the following results from the&nbsp;<span translate="no">GitHub Action: 1. Validate Secrets</span>.
+
+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&nbsp;<span translate="no">GitHub Action: 1. Validate Secrets</span>&nbsp;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&nbsp;<span translate="no">GitHub Action: 3. Create Certificates</span>&nbsp;.
+
+![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.

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"}

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.

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"}

docs/nightscout/remote-errors.md

@@ -26,7 +26,7 @@ If you attempt to issue a command from &nbsp;<span translate="no">Nightscout</sp
 Error: APNs delivery failed: BadDeviceToken
 ```
 
-If you attempt to issue a command using &nbsp;<span translate="no">Loop Caregiver</span>; 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 &nbsp;<span translate="no">Loop Caregiver</span>; after you authenticate the command, you will see the error message listed below and shown in the screenshot.
 
 ```
 HTTP Error

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
 

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)

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