Docs: add concrete example and CI test for update-ocaml-node script

- Update documentation with real commit example (31caeee) showing
  the exact command used to update from 3.2.0-alpha1 to 3.2.0-beta1
- Add CI job to test script reproducibility by verifying it produces
  the same file changes when run from the parent commit
- Update commit structure section to match actual commit patterns

Author: dannywillems

.github/workflows/test-docs-scripts.yml

@@ -172,3 +172,41 @@ jobs:
           # Docker Desktop needs to be started manually on macOS
           # We'll just check if it was installed via Homebrew
           docker --version || echo "Docker installed but not running (expected on macOS CI)"
+
+  test-update-ocaml-node-script:
+    name: Test Update OCaml Node Script
+    runs-on: [macos-latest, ubuntu-latest]
+
+      - name: Test update-ocaml-node script reproducibility
+        run: |
+          # Save the current script to use with the old commit state
+          cp ./website/docs/developers/scripts/update-ocaml-node.sh /tmp/update-ocaml-node.sh
+          chmod +x /tmp/update-ocaml-node.sh
+
+          # Check out the parent commit of the example update (cf67d94c)
+          git checkout cf67d94c
+
+          # Run the script from current branch with the same parameters as the example
+          /tmp/update-ocaml-node.sh 7f94ae0b 978866cd "3.2.0-alpha1" "3.2.0-beta1"
+
+          # Check if the changes match the expected diff from commit 31caeee6
+          git diff --name-only | sort > actual_files.txt
+          echo ".github/workflows/ci.yaml" > expected_files.txt
+          echo "docker-compose.archive.devnet.compare.yml" >> expected_files.txt
+          echo "node/testing/src/node/ocaml/config.rs" >> expected_files.txt
+          echo "node/testing/src/node/ocaml/mod.rs" >> expected_files.txt
+          echo "node/testing/src/scenarios/multi_node/basic_connectivity_peer_discovery.rs" >> expected_files.txt
+          echo "node/testing/src/scenarios/solo_node/basic_connectivity_accept_incoming.rs" >> expected_files.txt
+          sort expected_files.txt > expected_files_sorted.txt
+
+          # Verify the same files were modified
+          if ! diff -q actual_files.txt expected_files_sorted.txt; then
+            echo "ERROR: Script modified different files than expected"
+            echo "Expected files:"
+            cat expected_files_sorted.txt
+            echo "Actual files:"
+            cat actual_files.txt
+            exit 1
+          fi
+
+          echo "SUCCESS: Script produced the expected file changes"

website/docs/developers/updating-ocaml-node.md

@@ -33,8 +33,11 @@ OpenMina provides an automation script to handle the bulk of the update process:
 
 **Example usage:**
 
+For example, to update from `3.2.0-alpha1` to `3.2.0-beta1` (as done in commit
+[31caeee6](https://github.com/o1-labs/openmina/commit/31caeee6af7bf20b8578a23bf69718dbe68fe5cc)):
+
 ```bash
-./website/docs/developers/scripts/update-ocaml-node.sh 12345678 87654321 3.1.0 3.2.0-alpha1
+./website/docs/developers/scripts/update-ocaml-node.sh 7f94ae0b 978866cd "3.2.0-alpha1" "3.2.0-beta1"
 ```
 
 **Parameters:**
@@ -74,11 +77,13 @@ After making updates:
 
 ## 5. Commit Structure
 
-Following the pattern from PR #1236:
+Following the pattern from commit
+[31caeee6](https://github.com/o1-labs/openmina/commit/31caeee6af7bf20b8578a23bf69718dbe68fe5cc):
 
-1. **Main Update Commit**: "Update OCaml node dependencies to [version]"
-2. **Changelog**: Add entry documenting the version bump
-3. **Config Updates**: Separate commit for configuration file changes if needed
+1. **Main Update Commit**: "OCaml nodes: bump up to release [version]"
+   - Updates 6 files: CI workflows, Docker compose, and testing configurations
+   - Atomic change affecting all OCaml node references
+2. **Changelog**: Add entry documenting the version bump if needed
 
 ## Related Resources