Merge branch 'trunk' into emisar-d3aa

* trunk:
  moved version string calculation to bin/version-string.sh
  forgot one item in the ChangeLog
  ChangeLog: added 2023-12-03 release notes, converted @modelname to &modelname
  docs: expanded / reorganized info on Version Check formats
  updated MODELS, bin/models.py, and hw/BRANDS...
  fw3x: document how it ships with the wrong fuse values, and how to fix it
  github CI: fetch history too, to allow detection of version tags
  build-all: handle the case where "git describe" can't get any tags
  run CI on all branches, not just on trunk
  fetch tags on CI checkout, so 'git describe' can work
  added docs/battery-rainbow.png from old repo, since it's still relevant
  added bin/make-release.sh to generate a .zip file ready for release
  build-all.sh: re-indented, started organizing code into functions
  changed version number to use the latest release tag instead of build date

3 files changed, 63 insertions, 44 deletions

diff --git a/docs/anduril-manual.md b/docs/anduril-manual.md
index 93c6428..68c577c 100644
--- a/docs/anduril-manual.md
+++ b/docs/anduril-manual.md
@@ -728,26 +728,63 @@ Version Check Mode
 ------------------
 
 This allows people to see which version of the firmware is installed on
-their light.  The format for this is (usually) 12 digits -- a model
-number and a date.  `BBPP.YYYY-MM-DD`
+their light.  The format for this is usually a model number and a date.
+`MODEL.YYYY-MM-DD`
 
-  - `BB`: Brand ID
-  - `PP`: Product ID
+  - `MODEL`: Model number  
+     (usually `BBPP` where BB is the brand ID, and PP is the product ID)
   - `YYYY`: Year
   - `MM`: Month
   - `DD`: Day
 
-Versions before 2023-05-30 used `YYYYMMDDBBPP` format.
-Anduril 1 used only `YYYYMMDD` format, or none at all.
+The version number format has changed a few times, so write down the version
+info and check it against the formats below.
 
-The date is when the firmware was compiled.  If the vendor did not set
-this value, it defaults to 1969-07-20, the date of first human contact
-with the moon.  However, it might not be a date at all; some vendors may
-specify a completely different type of value here.
+The model number is very important when flashing new firmware.  Make sure
+the new firmware has the same model number as the old firmware.  More details
+on this are in [Which Hex File](which-hex-file.md).  Use the
+[MODELS](../MODELS) file to map a model number to the name of a .hex file.
 
-The brand/product values are also known as the model number.  These are
-hard-coded in the source code for each light's build target, and can be
-looked up in the "MODELS" file or by using the "make models" command.
+## Version Check Formats
+
+The Version Check function should blink out a series of numbers in one of
+several formats:
+
+ - `MODEL-YYYY-MM-DD-SINCE-DIRTY`
+   Anduril 2 from 2023-12 or later.  "SINCE" and "DIRTY" may be omitted.
+   Punctuation makes a "buzz" between sections.
+   - `MODEL`: model number
+   - `YYYY-MM-DD`: Year, month, day.  This uses the most recent release tag
+     from git, not the build date.
+   - `SINCE`: How many commits since the last official release tag?
+   - `DIRTY`: Adds a "-1" to the end if the repository was locally modified
+     without committing changes.
+
+ - `NNNN-YYYY-MM-DD`
+   Anduril 2 from 2023-05 or later.  
+   It's a model number and build date,
+   with "buzz" flashes between sections.
+   - `NNNN`: model number
+   - `YYYY`: year
+   - `MM`: month
+   - `DD`: day
+
+ - `YYYYMMDDNNNN`
+   Anduril 2 from 2023-05 or earlier.  
+   It's a build date and model number.
+
+- `YYYYMMDD`
+   This is an old Anduril 1 version.  It's just a build date.  
+   If the model name isn't obvious, try looking it up in the PRODUCTS file.
+
+- `1969-07-20`
+  The date of first human contact with the moon.  This value indicates that
+  the person who built the firmware probably made some sort of error.
+
+If the version doesn't include a model number, you may be able to find
+the model in the PRODUCTS file to see which firmware model it probably uses:
+
+  https://bazaar.launchpad.net/~toykeeper/flashlight-firmware/anduril2/view/head:/PRODUCTS
 
 
 Protection Features
@@ -811,6 +848,8 @@ In voltage mode, the colors follow the same sequence, in the same order
 as a rainbow...  with red indicating a low battery and purple indicating
 a full battery.
 
+![battery charge colors](battery-rainbow.png)
+
 For lights with a button LED, the button LED typically stays on while
 the main emitters are on.  Its brightness level is set in a way which
 mirrors the main LED -- off, low, or high.
diff --git a/docs/battery-rainbow.png b/docs/battery-rainbow.png
new file mode 100644
index 0000000..499866d
--- /dev/null
+++ b/docs/battery-rainbow.png
diff --git a/docs/which-hex-file.md b/docs/which-hex-file.md
index d59c6bd..3847217 100644
--- a/docs/which-hex-file.md
+++ b/docs/which-hex-file.md
@@ -1,41 +1,21 @@
 # How to figure out which .hex file to use
 
-1. Use the version check function (15 or more clicks from Off) to find out
+The name of a product is **not** enough information to find the right .hex
+file.  Ask the light what firmware it needs!
+
+1. Use the Version Check function (15 or more clicks from Off) to find out
    which flavor of the firmware the light has installed.  
    **WRITE THIS DOWN.**
 
 2. Look up the model number in the [MODELS file](../MODELS),
    to get the name and MCU type.
 
-3. Find the newest firmware for that model.  
-   https://github.com/ToyKeeper/anduril/releases  
-   https://toykeeper.net/torches/fsm/anduril2/?C=M;O=D
-
-If the version doesn't include a model number, you may be able to find
-the model in the PRODUCTS file to see which version it probably uses:
-
-  https://bazaar.launchpad.net/~toykeeper/flashlight-firmware/anduril2/view/head:/PRODUCTS
-
-
-## Version Check Formats
-
-The Version Check function should blink out a series of numbers in one of
-several formats:
-
- - `NNNN-YYYY-MM-DD`
-   Anduril 2 from 2023-05 or later.  
-   It's a model number and build date,
-   with "buzz" flashes between sections.
-   - `NNNN`: model number
-   - `YYYY`: year
-   - `MM`: month
-   - `DD`: day
-
- - `YYYYMMDDNNNN`
-   Anduril 2 from 2023-05 or earlier.  
-   It's a build date and model number.
+3. Find (or build) the newest firmware for that model.  
+   https://github.com/ToyKeeper/anduril/releases
 
-- `YYYYMMDD`
-   This is an old Anduril 1 version.  It's just a build date.  
-   If the model name isn't obvious, try looking it up in the PRODUCTS file.
+The Version Check format has changed a few times.  Use
+[this section of the manual](anduril-manual.md#Version_Check_Formats)
+to learn about those formats and how to use them.  In most cases, it should
+have a model number and a date... and you need the model number to find the
+correct .hex file.