Check the presence of changelog for the latest stable release in History.md (#1999)

* Documentation/History.md: update version format according to git tag for easiest automation

* Add test check for changelog of the latest stable version

* Add git config permissions routine to test docs via push.yml

* scripts/deploy.sh fixes

* making shellcheck happy due to false negative in deploy.sh

* push.yml: fetch tags for test docs

* push.yml: set fetch depth trying to get tags

* deploy.sh printf debugging

* deploy.sh: remove printf debugging

* push.yml: rename step from check_readme to check_docs to reflect its function

.github/workflows/push.yml

@@ -208,7 +208,7 @@ jobs:
           exclude: "./.git/*" # Optional.
           check_all_files_with_shebangs: "false" # Optional.
 
-  check_readme:
+  check_docs:
     runs-on: ubuntu-22.04
     container:
       image: alpine:3.19
@@ -220,6 +220,11 @@ jobs:
       - uses: actions/checkout@v4
         with:
           submodules: true
+          fetch-tags: true
+          fetch-depth: 0
 
-      - name: Check autogenerated Documentation/README.md
+      - name: Git ownership exception
-        run: /bin/sh ./scripts/deploy.sh docs_readme
+        run: git config --global --add safe.directory /__w/IronOS/IronOS && git config --global safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Check and verify documentation
+        run: /bin/sh ./scripts/deploy.sh docs

Documentation/History.md

@@ -1,7 +1,7 @@
 # Version Changes
 
 
-## V2.22
+## v2.22
 
 ### New Hardware Support
 
@@ -45,7 +45,7 @@ Assets have been made for rendering this at full size, but the code is not compl
 - Lots of tooling and code cleanups
 
 
-## V2.21
+## v2.21
 
 ### Features & changes
 
@@ -64,7 +64,7 @@ Alternatively you can use Spagett1's PineFlash tool that should provide a GUI in
 For a small number of V2 Pinecil devices there appears to be an interference issue between the Bluetooth Low Energy and some devices; more information here. If this occurs to you, please let us know in the issue and rollback to 2.20 for now.
 
 
-## V2.20
+## v2.20
 
 - First "full" release for PinecilV2
 - Loots of documentation updates
@@ -73,7 +73,7 @@ For a small number of V2 Pinecil devices there appears to be an interference iss
 - Cold Junction Calibration was reworked and now occurs _at next boot_ to make it easier to perform when the device is cold
 
 
-## V2.19
+## v2.19
 
 - Bug-fix Infinite Boot Logo
 - Shutdown settings for MHP30
@@ -84,7 +84,7 @@ For a small number of V2 Pinecil devices there appears to be an interference iss
 - Improved documents, added features table
 
 
-## V2.18
+## v2.18
 
 - Support for animated bootup logo's
 - Bootup logo's moved to their own IronOS-Meta repo
@@ -94,7 +94,7 @@ For a small number of V2 Pinecil devices there appears to be an interference iss
 - Better Instructions/documents
 
 
-## V2.17
+## v2.17
 
 ### Features & changes
 
@@ -122,7 +122,7 @@ For a small number of V2 Pinecil devices there appears to be an interference iss
 - -> Release has been updated to build `e065be3` after one bug with the BMA223 was found.
 
 
-## V2.16
+## v2.16
 
 - Overhaul of the Timer+ADC setup with help from @sandmanRO
 - Overhaul of the PID with help from @sandmanRO
@@ -140,7 +140,7 @@ For a small number of V2 Pinecil devices there appears to be an interference iss
 - Romanian language added
 
 
-## V2.15
+## v2.15
 
 ### Features & changes
 
@@ -165,7 +165,7 @@ Programs the same as any one Miniware unit using drag and drop.
 The flood doors are now open for feature requests for this unit :)
 
 
-## V2.14
+## v2.14
 
 - Fixing auto rotation bug in the LIS accelerometer in the TS80/TS80P
 - Adds support for two new accelerometers
@@ -183,7 +183,7 @@ The flood doors are now open for feature requests for this unit :)
 - clang-format spec setup #801
 
 
-## V2.13
+## v2.13
 
 - First _official_ Pinecil release
 - All of the wire for Pinecil releases added
@@ -201,7 +201,7 @@ The flood doors are now open for feature requests for this unit :)
 - Rework of all of the temperature curves for better accuracy
 
 
-## V2.12
+## v2.12
 
 - Only released as pre-release
 - [TS80P] Improvements to the PD negotiation to handle a few more adapters cleanly
@@ -210,21 +210,21 @@ The flood doors are now open for feature requests for this unit :)
 - Removing the very old single line menu style.
 
 
-## V2.11
+## v2.11
 
 - First TS80P support
 - Added in a USB-PD driver stack for the FUSB302
 - Fixed some graphical glitches
 
 
-## V2.10
+## v2.10
 
 - GUI polish (animations and scroll bars)
 - Power pulse to keep power supplies alive
 - Adjustable tip response gain
 
 
-## V2.09
+## v2.09
 
 - Adjustable steps in temperature adjustment
 - Git hash now in build string
@@ -232,19 +232,19 @@ The flood doors are now open for feature requests for this unit :)
 - Some minor QC3 improvements
 
 
-## V2.08
+## v2.08
 
 - Fixes auto start in sleep mode
 - Power limiters
 
 
-## V2.07
+## v2.07
 
 - QC fixes
 - Cosmetic fixes for leading 0's
 
 
-## V2.06
+## v2.06
 
 - Warning on settings reset
 - Temp temp re-write
@@ -253,32 +253,32 @@ The flood doors are now open for feature requests for this unit :)
 - Menu timeouts
 
 
-## V2.05
+## v2.05
 
 - Language updates
 
 
-## V2.04
+## v2.04
 
 - GUI updates
 
 
-## V2.03
+## v2.03
 
 - Support for new accelerometers
 
 
-## V2.02
+## v2.02
 
 - Adds small font
 
 
-## V2.01
+## v2.01
 
 - Newer settings menu
 
 
-## V2.00
+## v2.00
 
 - Complete re-write of the low layer system to use the STM32 HAL for easier development
 - This allowed easier setup for the new ADC auto measuring system
@@ -289,7 +289,7 @@ The flood doors are now open for feature requests for this unit :)
 - Added smaller font for said screen views
 
 
-## V1.17
+## v1.17
 
 - Added blinking cooldown display
 - Allowed smaller sleep timeout values
@@ -297,72 +297,72 @@ The flood doors are now open for feature requests for this unit :)
 - Automatic startup option
 
 
-## V1.16
+## v1.16
 
 - Added automatic rotation support
 - Added power display graph
 
 
-## V1.15
+## v1.15
 
 - Added support for a custom bootup logo to be programmed via the DFU bootloader
 
 
-## V1.14
+## v1.14
 
 - Changed input voltage cutoff to be based on cell count rather than voltage
 
 
-## V1.13
+## v1.13
 
 - Swapped buttons for menu to prevent accidentally changing first menu item
 - Added auto key repeat
 
 
-## V1.12
+## v1.12
 
 - Increases sensitivity options to be 1\*9 with 0 off state
 - Fixes issue where going from COOL \*> soldering can leave screen off
 
 
-## V1.11
+## v1.11
 
 - Boost mode
 - Change sensitivity options to be 1\*8
 
 
-## V1.10
+## v1.10
 
 - Adds help text to settings
 - Improves settings for the display update rate
 
 
-## V1.09
+## v1.09
 
 - Adds display modes, for slowing down or simplifying the display
 
 
-## V1.08
+## v1.08
 
 - Fix settings menu not showing flip display
 
 
-## V1.07
+## v1.07
 
 - Adds shutdown time to automatically shutdown the iron after inactivity
 
 
-## V1.06
+## v1.06
 
 - Changes H and C when the iron is heating to the minidso chevron like images
 
 
-## V1.05
+## v1.05
 
 - Adds ability to calibrate the input voltage measurement
 
 
-## V1.04
+## v1.04
 
 - Increased accuracy of the temperature control
 - Improved PID response slightly
@@ -370,14 +370,14 @@ The flood doors are now open for feature requests for this unit :)
 - Nicer idle screen
 
 
-## V1.03
+## v1.03
 
 - Improved Button handling
 - Ability to set motion sensitivity
 - DC voltmeter page shows input voltage
 
 
-## V1.02
+## v1.02
 
 - Adds hold both buttons on IDLE to access the therometer mode
 - Changes the exit soldering mode to be holding both buttons (Like original firmware)

Makefile

@@ -144,12 +144,12 @@ docs: $(MKDOCS_YML)  Documentation/*  Documentation/Flashing/*  Documentation/im
 docs-deploy: $(MKDOCS_YML)  Documentation/*  Documentation/Flashing/*  Documentation/images/*
 	$(MKDOCS)  gh-deploy  -f $(MKDOCS_YML)  -d ../site
 
-# routine check for autogenerated Documentation/README.md
+# routine check to verify documentation
 test-md:
 	@echo ""
-	@echo "---- Checking REAMDE.md... ----"
+	@echo "---- Checking documentation... ----"
 	@echo ""
-	@/bin/sh  ./scripts/deploy.sh  docs_readme
+	@/bin/sh  ./scripts/deploy.sh  docs
 
 # shell style & linter check (github CI version of shellcheck is more recent than alpine one so the latter may not catch some policies)
 test-sh:

scripts/deploy.sh

@@ -19,7 +19,9 @@ usage()
 	echo -e "\tbuild - compile builds of IronOS inside docker container for supported hardware"
 	echo -e "\tclean - delete created docker image for IronOS & its build cache objects\n"
 	echo "CMD (helper routines):"
+	echo -e "\tdocs - high level target to run docs_readme and docs_history (see below)\n"
 	echo -e "\tdocs_readme - generate & OVERWRITE(!) README.md inside Documentation/ based on nav section from mkdocs.yml if it changed\n"
+	echo -e "\tdocs_history - check if History.md has the changelog for the latest stable release\n"
 	echo -e "\tcheck_style_file SRC - run code style checks based on clang-format & custom parsers for source code file SRC\n"
 	echo -e "\tcheck_style_log - run clang-format using source/Makefile and generate gcc-compatible error log in source/check-style.log\n"
 	echo -e "STORAGE NOTICE: for \"shell\" and \"build\" commands extra files will be downloaded so make sure that you have ~5GB of free space.\n"
@@ -71,6 +73,23 @@ EOF
 	return "${ret}"
 }
 
+# Documentation/History.md automagical changelog routine
+docs_history()
+{
+	md="Documentation/History.md"
+	ver_md="$(sed -ne 's/^## //1p' "${md}" | head -1)"
+	echo "Latest changelog: ${ver_md}"
+	ver_git="$(git tag -l | sort | grep -e "^v" | grep -v "rc" | tail -1)"
+	echo "Latest release tag: ${ver_git}"
+	ret=0
+	if [ "${ver_md}" != "${ver_git}" ]; then
+		ret=1
+		echo "It seems there is no changelog information for ${ver_git} in ${md} yet."
+		echo "Please, update changelog information in ${md}."
+	fi;
+	return "${ret}"
+}
+
 # Helper function to check code style using clang-format & grep/sed custom parsers:
 # - basic logic moved from source/Makefile : `check-style` target for better maintainance since a lot of sh script involved;
 # - output goes in gcc-like error compatible format for IDEs/editors.
@@ -126,27 +145,42 @@ docker_file="-f ${root_dir}/${docker_conf}"
 # (compose sub-command must be included, i.e. DOCKER_BIN="/usr/local/bin/docker compose" ./deploy.sh)
 
 if [ -z "${DOCKER_BIN}" ]; then
-	docker_bin=""
+	docker_app=""
 else
-	docker_bin="${DOCKER_BIN}"
+	docker_app="${DOCKER_BIN}"
 fi;
 
 # detect availability of docker
 
 docker_compose="$(command -v docker-compose)"
-if [ -n "${docker_compose}" ] && [ -z "${docker_bin}" ]; then
+if [ -n "${docker_compose}" ] && [ -z "${docker_app}" ]; then
-	docker_bin="${docker_compose}"
+	docker_app="${docker_compose}"
 fi;
 
 docker_tool="$(command -v docker)"
-if [ -n "${docker_tool}" ] && [ -z "${docker_bin}" ]; then
+if [ -n "${docker_tool}" ] && [ -z "${docker_app}" ]; then
-	docker_bin="${docker_tool}  compose"
+	docker_app="${docker_tool}  compose"
 fi;
 
 # give function argument a name
 
 cmd="${1}"
 
+# meta target to verify markdown documents
+
+if [ "docs" = "${cmd}" ]; then
+	docs_readme
+	readme="${?}"
+	docs_history
+	hist="${?}"
+	if [ "${readme}" -eq 0 ] && [ "${hist}" -eq 0 ]; then
+		ret=0
+	else
+		ret=1
+	fi;
+	exit ${ret}
+fi;
+
 # if only README.md for Documentation update is required then run it & exit
 
 if [ "docs_readme" = "${cmd}" ]; then
@@ -154,6 +188,13 @@ if [ "docs_readme" = "${cmd}" ]; then
 	exit "${?}"
 fi;
 
+# if only History.md for Documentation update is required then run it & exit
+
+if [ "docs_history" = "${cmd}" ]; then
+	docs_history
+	exit "${?}"
+fi;
+
 if [ "check_style_file" = "${cmd}" ]; then
 	check_style_file "${2}"
 	exit "${?}"
@@ -166,7 +207,7 @@ fi;
 
 # if docker is not presented in any way show warning & exit
 
-if [ -z "${docker_bin}" ]; then
+if [ -z "${docker_app}" ]; then
 	echo "ERROR: Can't find docker-compose nor docker tool. Please, install docker and try again."
 	exit 1
 fi;
@@ -194,6 +235,6 @@ if [ "${cmd}" = "shell" ]; then
 echo -e "\t* type \"exit\" to end the session when done;"
 fi;
 echo -e "\t* type \"${0} clean\" to delete created container (but not cached data)"
-echo -e "\n====>>>> ${docker_bin}  ${docker_file}  ${docker_cmd}\n"
+echo -e "\n====>>>> ${docker_app}  ${docker_file}  ${docker_cmd}\n"
-eval "${docker_bin}  ${docker_file}  ${docker_cmd}"
+eval "${docker_app}  ${docker_file}  ${docker_cmd}"
 exit "${?}"