Merge pull request #1252 from o1-labs/dw/scripts-to-update-ocaml-node

Scripts to update OCaml node

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"

CHANGELOG.md

@@ -20,6 +20,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Documentation**: Add instructions to update the OCaml node dependencies.
   ([#1237](https://github.com/o1-labs/openmina/pull/1237))
+- **Development Tools**: Automation script for updating OCaml node references
+  with comprehensive documentation and CI testing to ensure reproducibility
+  ([#1252](https://github.com/o1-labs/openmina/pull/1252))
 - **Documentation**: Complete Docusaurus-based documentation website with
   comprehensive guides for node runners, developers, and researchers
   ([#1234](https://github.com/o1-labs/openmina/pull/1234)). It migrates all the

website/docs/developers/scripts/update-ocaml-node.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+set -eou pipefail
+
+# Checkout to the root directory of the project
+# We suppose this script is run from a copy of the git repository.
+base_dir="$(git rev-parse --show-toplevel)"
+
+if [ "$#" -ne 4 ]; then
+    echo "Error: Missing arguments."
+    echo "Usage: $0 <old_hash> <new_hash> <old_version> <new_version>"
+    exit 1
+fi
+
+old_hash=$1
+new_hash=$2
+old_version=$3
+new_version=$4
+
+length_old_hash=${#old_hash}
+length_new_hash=${#new_hash}
+
+if [ "$length_old_hash" -ne 8 ] || [ "$length_new_hash" -ne 8 ]; then
+    echo "Error: Hashes must be exactly 8 characters long."
+    echo "Old hash: $old_hash, New hash: $new_hash"
+    echo "The correct hashes can be found on the GitHub release page of MinaProtocol/Mina."
+    exit 1
+fi
+
+# The docker images are named with only 7 characters of the hash.
+shorter_old_hash=${old_hash:0:7}
+shorter_new_hash=${new_hash:0:7}
+
+echo "Updating config_${old_hash} to config_${new_hash}"
+sed -i'' -e "s/config_${old_hash}/config_${new_hash}/g" \
+    "${base_dir}"/node/testing/src/node/ocaml/config.rs \
+    "${base_dir}"/node/testing/src/node/ocaml/mod.rs \
+    "${base_dir}"/node/testing/src/scenarios/multi_node/basic_connectivity_peer_discovery.rs \
+    "${base_dir}"/node/testing/src/scenarios/solo_node/basic_connectivity_accept_incoming.rs
+sed -i'' -e "s/${old_version}-${shorter_old_hash}/${new_version}-${shorter_new_hash}/g" \
+    "${base_dir}"/.github/workflows/ci.yaml \
+    "${base_dir}"/docker-compose.archive.devnet.compare.yml \
+    "${base_dir}"/node/testing/src/node/ocaml/config.rs

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

@@ -18,58 +18,53 @@ Visit the
 find the latest release version and associated container image tags.
 
 For example, release `3.2.0-alpha1` provides updated container images and
-configuration files.
+configuration files. You'll need:
 
-## 2. Update GCR Links in Code
+- The new version number (e.g., `3.2.0-alpha1`)
+- The 8-character configuration hash from the release page
 
-Use `git grep` to find all Google Container Registry (GCR) references that need
-updating:
+## 2. Automated Update with Script
 
-```bash
-# Search for GCR image references
-git grep "gcr.io/o1labs-192920/mina-daemon"
+OpenMina provides an automation script to handle the bulk of the update process:
 
-# Search for any mina-daemon references
-git grep "mina-daemon"
+```bash
+./website/docs/developers/scripts/update-ocaml-node.sh <old_hash> <new_hash> <old_version> <new_version>
 ```
 
-Update the image tags in the found files to match the new release version.
-Typically this involves changing version strings in Docker Compose files,
-testing configurations, and CI workflows.
+**Example usage:**
 
-## 3. Update Configuration Files
+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)):
 
-Update the configuration file hash to match the new release. The config files
-with the pattern `config_[8-character-hash]` come from the OCaml node release
-and need to be referenced in the OpenMina codebase.
-
-The configuration hash corresponds to the genesis state and network parameters
-for the specific release. You may need to:
+```bash
+./website/docs/developers/scripts/update-ocaml-node.sh 7f94ae0b 978866cd "3.2.0-alpha1" "3.2.0-beta1"
+```
 
-- Update references to the config filename in code to match the new hash
-- Download or reference the new config files from the OCaml node release
-- Verify the new configuration is compatible with OpenMina
+**Parameters:**
 
-## 4. Example Workflow
+- `old_hash`: Current 8-character config hash
+- `new_hash`: New 8-character config hash from the release
+- `old_version`: Current version (e.g., `3.1.0`)
+- `new_version`: New version (e.g., `3.2.0-alpha1`)
 
-Based on PR #1236, a typical update involves:
+The script automatically updates:
 
-```bash
-# 1. Find current references
-git grep "gcr.io/o1labs-192920/mina-daemon"
-git grep "3\.1\.0" # Search for old version numbers
+- Configuration file references in testing code
+- Docker image tags in CI workflows and compose files
+- Version strings throughout the codebase
 
-# 2. Update image tags throughout the codebase
-# Replace old tags with new release version
+## 3. Manual Verification
 
-# 3. Search for config file references in code
-git grep "config_"
+After running the script, verify all references were updated correctly:
 
-# 4. Update any hardcoded version references
-git grep -i "mina.*3\.1\.0" # Example for version 3.1.0
+```bash
+# Search for any remaining old references
+git grep "gcr.io/o1labs-192920/mina-daemon"
+git grep "config_<old_hash>"
+git grep "<old_version>"
 ```
 
-## 5. Verification Steps
+## 4. Verification Steps
 
 After making updates:
 
@@ -80,13 +75,15 @@ After making updates:
    with the updated OCaml node
 5. **CI Pipeline**: Verify that automated testing passes with new versions
 
-## 6. Commit Structure
+## 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