From 45c3b49ff4be1cd0b3982a8d8b851227c7e9327f Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 2 Feb 2026 23:31:24 +0100
Subject: docs: Add submodule update instructions to HOWTO.md

---
 doc/HOWTO.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

(limited to 'doc')

diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index e97380e..d402453 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -119,6 +119,47 @@ cd ..
 
 ## Tools
 
+### Updating Submodules
+
+To ensure all `third_party/` submodules are updated to the latest "Tip of Tree" (ToT) from their respective remote repositories and to resolve any local diffs, follow these steps:
+
+1.  **Enter the submodule directory** (e.g., `third_party/wgpu-native`):
+    ```bash
+    cd third_party/wgpu-native
+    ```
+
+2.  **Fetch the latest changes from the remote**:
+    ```bash
+    git fetch
+    ```
+
+3.  **Identify the default branch** (e.g., `main`, `master`, `trunk`). You can see remote branches with `git branch -r`. For `wgpu-native`, the main development branch is typically `trunk`.
+
+4.  **Checkout the default branch and hard reset to its remote state** (this discards any local changes and ensures a clean ToT):
+    ```bash
+    git checkout trunk
+    git reset --hard origin/trunk
+    ```
+    (Replace `trunk` with the correct branch name if different for other submodules.)
+
+5.  **Return to the superproject's root directory**:
+    ```bash
+    cd ../..
+    ```
+
+6.  **Update the superproject's record of the submodule**: This stages the change in the superproject's `.git` index, updating the commit hash for the submodule.
+    ```bash
+    git add third_party/wgpu-native
+    ```
+
+7.  **Commit the submodule update** in the superproject:
+    ```bash
+    git commit -m "chore: Update third_party/wgpu-native submodule"
+    ```
+    (Adjust the commit message as appropriate for other submodules.)
+
+Repeat these steps for any other submodules in `third_party/` that need updating.
+
 ### Spectrogram Tool (`spectool`)
 
 A command-line tool for analyzing WAV and MP3 files into spectrograms and playing them back.
-- 
cgit v1.2.3