fix: document the script

Signed-off-by: Terry Howe <[email protected]>

Author: TerryHowe

scripts/README

@@ -1,4 +1,24 @@
 #!/bin/bash
+#
+# Helm Documentation Update Script
+#
+# This script automatically updates the Helm website (helm.sh) with the latest
+# release information for versions of Helm. It performs the following tasks:
+#
+# 1. Fetches the latest stable releases from GitHub API
+# 2. Compares with current versions in config.toml
+# 3. Updates version references if a new significant release is found
+# 4. For v3 updates: also updates go.mod dependencies and CLI documentation
+# 5. For v2 updates: only updates version references (legacy support)
+#
+# Usage: ./update-docs.sh <v2|v3>
+#
+# The script only updates for significant releases (minor version bumps or
+# newer patch versions). It creates backups and validates all changes before
+# committing them.
+#
+# Dependencies: curl, jq, docker (for CLI docs), go (for v3 go.mod updates)
+#
 set -euo pipefail
 
 # Colors for output
@@ -7,18 +27,24 @@ GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
-# Check for required parameter
+# Validate command line arguments
 if [ $# -ne 1 ] || { [ "$1" != "v2" ] && [ "$1" != "v3" ]; }; then
     echo -e "${RED}Usage: $0 <v2|v3>${NC}"
     echo -e "${YELLOW}Specify either 'v2' or 'v3' to update only that major version${NC}"
     exit 1
 fi
-VERSION="$1"
-PRIMARY_VERSION="v3"
+
+# Global configuration
+VERSION="$1"                # Version to update (v2 or v3)
+PRIMARY_VERSION="v3"        # Primary version for go.mod and CLI docs
 
 echo -e "${GREEN}🔄 Starting Helm documentation update process for $VERSION only...${NC}"
 
-# Function to log messages
+# =============================================================================
+# UTILITY FUNCTIONS
+# =============================================================================
+
+# Logging functions with timestamps and color coding
 log() {
     echo -e "${GREEN}[$(date +'%Y-%m-%d %H:%M:%S')] $1${NC}"
 }
@@ -31,18 +57,21 @@ error() {
     echo -e "${RED}[$(date +'%Y-%m-%d %H:%M:%S')] ERROR: $1${NC}"
 }
 
-# Function to compare semantic versions
+# Compare semantic versions - returns 0 if $1 > $2
 version_gt() {
-    # Returns true if $1 > $2
     printf '%s\n%s\n' "$2" "$1" | sort -V -C
 }
 
-# Function to extract major.minor from version
+# Extract major.minor version from full version string (e.g., v3.15.2 -> 3.15)
 get_major_minor() {
     echo "$1" | sed -E 's/^v([0-9]+\.[0-9]+)\..*$/\1/'
 }
 
-# Function to get latest releases from GitHub API
+# =============================================================================
+# DATA RETRIEVAL FUNCTIONS
+# =============================================================================
+
+# Fetch all stable releases from GitHub API (excludes pre-releases)
 get_latest_releases() {
     log "Fetching latest releases from GitHub API..."
 
@@ -51,23 +80,27 @@ get_latest_releases() {
     curl -s "https://api.github.com/repos/helm/helm/releases?per_page=100" | jq -r '.[] | select(.prerelease == false) | .tag_name'
 }
 
-# Function to get current versions from config.toml
+# Get current version for the specified major version from config.toml
 get_current_version() {
     REGEX="version = \"${VERSION}\."
     grep -A 1 "${REGEX}" config.toml | head -1 | sed -E 's/.*version = "([^"]+)".*/\1/'
 }
 
-# Function to get current Helm version from go.mod
+# Check if we're updating the primary version (which requires additional updates)
 is_primary_version() {
     test "$VERSION" == "${PRIMARY_VERSION}"
 }
 
-# Function to get current Helm version from go.mod
+# Get current Helm version from go.mod (only relevant for primary version)
 get_current_gomod_version() {
     grep "helm.sh/helm/${PRIMARY_VERSION}" sdkexamples/go.mod | awk '{print $2}' | head -1
 }
 
-# Function to update config.toml version
+# =============================================================================
+# UPDATE FUNCTIONS
+# =============================================================================
+
+# Update version reference in Hugo config.toml with backup and validation
 update_config_version() {
     local old_version="$1"
     local new_version="$2"
@@ -76,7 +109,7 @@ update_config_version() {
 
     # Create a backup
     cp config.toml config.toml.bak
-    
+
     # Update the version in config.toml
     cat config.toml.bak | sed "s/version = \"$old_version\"/version = \"$new_version\"/" >config.toml
 
@@ -92,24 +125,25 @@ update_config_version() {
     fi
 }
 
-# Function to update go.mod
+# Update Go module dependencies to use the new Helm version (v3 only)
 update_gomod() {
     local new_version="$1"
 
     log "Updating sdkexamples/go.mod to Helm $new_version"
 
     cd sdkexamples
 
-    # Update the go.mod file
+    # Update the go.mod file to require the new version
     go mod edit -require="helm.sh/helm/${PRIMARY_VERSION}@$new_version"
-    go mod tidy
+    go mod tidy  # Clean up dependencies
 
     cd ..
 
     log "✅ Successfully updated go.mod"
 }
 
-# Function to run helm docs command
+# Generate fresh CLI documentation using Docker (v3 only)
+# This uses the get-helm-3 script to install the latest Helm and generate docs
 update_helm_docs() {
     log "Updating Helm CLI documentation..."
 
@@ -133,53 +167,63 @@ update_helm_docs() {
     fi
 }
 
-# Main execution
+# =============================================================================
+# MAIN EXECUTION LOGIC
+# =============================================================================
+
+# Main function that orchestrates the update process
 main() {
     local changes_made=false
 
     local current_version=$(get_current_version)
     local current_gomod=$(get_current_gomod_version)
 
+    # Display current state
     log "Current versions:"
     log "  $VERSION in config.toml: $current_version"
-    if is_primary_version
-    then
+    if is_primary_version; then
         log "  $VERSION in go.mod: $current_gomod"
     fi
 
-    # Find latest release only
+    # Find the latest stable release for this major version
     local latest_version=$(get_latest_releases | grep "^${VERSION}\." | head -1)
 
     log "Latest releases found:"
     log "  ${VERSION}: $latest_version"
 
-    # Check if we need to update version in config.toml
+    # Determine if an update is needed and perform it
     if [ -n "$latest_version" ] && [ "$latest_version" != "$current_version" ]; then
         # Check if this is a new minor release (not just patch)
         local current_minor=$(get_major_minor "$current_version")
         local latest_minor=$(get_major_minor "$latest_version")
 
+        # Only update for significant releases (minor bumps or newer patches)
         if [ "$current_minor" != "$latest_minor" ] || version_gt "$latest_version" "$current_version"; then
             log "🔄 New ${VERSION} release detected: $latest_version (current: $current_version)"
+            
+            # Update the version in config.toml
             if update_config_version "$current_version" "$latest_version"; then
                 changes_made=true
 
-                if is_primary_version
-                then
-                    # Update go.mod if it's different
+                # For primary version (v3), also update go.mod and documentation
+                if is_primary_version; then
+                    # Update go.mod dependencies if version differs
                     if [ "$latest_version" != "$current_gomod" ]; then
                         update_gomod "$latest_version"
                     fi
 
-                    # Update documentation
+                    # Regenerate CLI documentation
                     update_helm_docs
                 fi
             fi
         else
-            log "V3 version $latest_version is not a significant update from $current_version"
+            log "${VERSION} version $latest_version is not a significant update from $current_version"
         fi
+    else
+        log "No new ${VERSION} releases found or version is already current"
     fi
 
+    # Report final status
     if [ "$changes_made" = true ]; then
         log "✅ Documentation update completed with changes for $VERSION"
         exit 0