From 665713d0feb5c7fa26686a8c29bf94f9233ef294 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Sat, 1 Feb 2025 11:11:09 -0500 Subject: [PATCH] Add clarifications to docs on creating labs Signed-off-by: David A. Wheeler --- docs/labs/create_checker.md | 63 +++++++++++++++++++++++++++++++++---- 1 file changed, 57 insertions(+), 6 deletions(-) diff --git a/docs/labs/create_checker.md b/docs/labs/create_checker.md index 402baba7..7a490772 100644 --- a/docs/labs/create_checker.md +++ b/docs/labs/create_checker.md @@ -1,6 +1,17 @@ # Creating labs with checker -These are the instructions for how to create labs with `checker.js`, +These are the instructions for how to create labs with `checker.js`. +The main sections are: + +* [Introduction](#introduction) +* [Creating the lab instructions and correct answer](#creating-the-lab-instructions-and-correct-answer) +* [Creating the lab HTML file](#creating-the-lab-html-file) +* [Creating the lab JavaScript file](#creating-the-lab-javascript-file) + (including [JavaScript notation](#javascript-notation) and + [Debugging](#debugging)) +* [Localization](#localization) (aka translation) +* [Submitting a new or updated lab](#submitting-a-new-or-updated-lab) +* [Potential future directions](#potential-future-directions) ## Introduction @@ -149,15 +160,38 @@ has its advantages: These are often useful for patterns. Use ${BACKQUOTE} for ` and ${DOLLAR} for $. -JavaScript allows trailing commas, and we encourage using them. +A common error is including the terminating character in the middle of +a string. For example, this is an error: `"A "foo" is metasyntactic variable"` +because the double-quote before `foo` is interpreted as the end of the string. +Some correct alternatives would be +`"A \"foo\" is metasyntactic variable"` +or +`'A "foo" is metasyntactic variable'` (either works). + +Values (including strings) +are grouped into two kinds of structures, *arrays* and *objects*: + +* array: An ordered sequence of values with this form: `[a, b, c]` +* object: A set of properties and their values with this form: + `{property1: value1, property2: value2, property3: value3}` + +A *really* *common* error is +forgetting to add a comma to separate items +when you add an item to an array or object. +For example, if you add `d` to the array earlier, you might have this +incorrect form: `[a, b, c d]` (ERRONEOUS). + +JavaScript allows trailing commas, and we *encourage* using them. In other words, a list in JavaScript can have the form `[ 'a', 'b', 'c', ]` -(note the trailing comma after `'c'`). +(note the trailing extra comma after `'c'`). Using trailing commas reduces the likelihood of -a common error: forgetting to add a comma when you add an item to a list. -Using trailing commas means that when you add a new item (`'d'`) at the end, +forgetting to add the comma between values. +If you using trailing commas, when you add a new item (`'d'`) at the end, you *already* have the comma ready for use. +If things don't work out, see the [Debugging](#debugging) section. + ### Expressing correct answer patterns The patterns used for `correct` and `hints` @@ -347,6 +381,9 @@ You can provide these fields for testing: * `hints`: If present, this is an array of hints. We discuss that now. +We encourage creating many self-tests (`successes`, `failures`, and +tests for hints). + ### Hints Hints are expressed in the info `hints` field. @@ -449,7 +486,11 @@ These tests are automatically checked every time the page is (re)loaded. Sadly, sometimes things don't work; here are some debugging tips for labs. -If you open a page and the text entries don't have color, there +Every time you reload the lab HTML, the program will reload and +all self-tests will be run. If you see no errors, and the text entry +areas are showing in yellow, a *lot* of things are working well. + +If you load a page and the text entries don't have color, there was a serious problem loading things. Use your browser's *Developer Tools* to show details. In Chrome, this is More Tools -> Developer Tools -> (Console Tab). @@ -463,11 +504,17 @@ Note: this reports an attempt to load a file that's hosted on GitHub pages, and that page is unlikely to exist on your local machine. +We encourage you to add many self-tests (e.g., `successes`, `failures`, and +tests for hints) when creating labs. + You can set the optional info "debug" field to true. This will display information, particularly on its inputs. This can help you track down a problems if you think your inputs are being interpreted in a way different than you expect. +See the [JavaScript notation](#javascript-notation) section on how to write +data in JavaScript. + ### Advanced use: Definitions Regular expressions make it easy to describe many patterns. @@ -629,6 +676,10 @@ The [list of labs](https://best.openssf.org/labs/) provides more information. WARNING: We aren't currently using all labs we have. Make sure you focus on the labs in use first :-). +See the [JavaScript notation](#javascript-notation) section on how to write +data, and +the [Debugging](#debugging) section to see how to understand and fix problems. + ### No longer using embedded data or YAML At one time we used data files embedded in the HTML (e.g., YAML,