Harmony Version Management Skill

Purpose

Manage Harmony package versions, check for updates, and handle Optum's package curation policies (5-day delay).

Check Current Harmony Versions

Installed Packages

npm list @uhg-harmony/react @uhg-harmony/foundations @uhg-harmony/icons-react

Available Versions in Registry

# Check all available versions
npm view @uhg-harmony/react versions

# Check latest version (may be blocked by Optum policy)
npm view @uhg-harmony/react version

# Check version publish dates
npm view @uhg-harmony/react time

Update Strategy

Step 1: Identify Safe Versions

# Get versions older than 5 days
npm view @uhg-harmony/react time | tail -20

# Current date reference
date

Rule: Only use versions published more than 5 days ago to avoid Optum blocks.

Step 2: Update package.json

Option A: Specific Version (Recommended)

{
  "dependencies": {
    "@uhg-harmony/react": "1.2.3",
    "@uhg-harmony/foundations": "1.2.3",
    "@uhg-harmony/icons-react": "1.2.3"
  }
}

Option B: Range with Overrides

{
  "dependencies": {
    "@uhg-harmony/react": "^1.2.0",
    "@uhg-harmony/foundations": "^1.2.0"
  },
  "overrides": {
    "@uhg-harmony/react": "1.2.3"
  }
}

Step 3: Update and Verify

# Install with new versions
npm install

# Verify installation
npm list @uhg-harmony/react

Handle Blocked Versions

If you encounter 403 errors:

# Error example:
# npm notice package @uhg-harmony/react:1.3.0 download was blocked
# Package version is 3 days old, Use an older version or wait

# Solution: Find older compatible version
npm view @uhg-harmony/react time | grep "2025-01"

# Use version from 5+ days ago
npm install @uhg-harmony/[email protected]

Version Compatibility Matrix

Harmony React	Foundations	Icons	React Version	Node Version
^1.2.0	^1.2.0	^1.2.0	≥18.3.0	≥20.x
^1.1.0	^1.1.0	^1.1.0	≥18.2.0	≥18.x

Update Checklist

• Check current versions: npm list @uhg-harmony/*
• View available versions: npm view @uhg-harmony/react versions
• Verify publish dates (5+ days old)
• Update package.json with specific version
• Remove node_modules and package-lock.json
• Run npm install
• Test application build: npm run build
• Test application runtime: npm run dev
• Verify no console warnings
• Check for breaking changes in release notes

Breaking Change Resources

• GitHub Releases: https://github.com/OptumInsight-Platform/harmony/releases
• Storybook: https://storybook-harmony.ofp-elr.optum.com/
• Teams Channel: Harmony Support

Common Update Scenarios

Scenario 1: Minor Version Update

# Safe - patch/minor updates
npm install @uhg-harmony/[email protected]

Scenario 2: Major Version Update

# Review breaking changes first
# Update React if needed
npm install [email protected] [email protected]

# Then update Harmony
npm install @uhg-harmony/[email protected]

Scenario 3: Update All Harmony Packages

# Use same version across all packages
npm install @uhg-harmony/[email protected] \
  @uhg-harmony/[email protected] \
  @uhg-harmony/[email protected]

Troubleshooting

Issue: Version conflicts

# Clear npm cache
npm cache clean --force

# Reinstall
rm -rf node_modules package-lock.json
npm install

Issue: Peer dependency warnings

# Check peer dependencies
npm view @uhg-harmony/react peerDependencies

# Install missing peers
npm install [email protected] [email protected] styled-components@^5.3.11

Automation Script

Create scripts/update-harmony.sh:

#!/bin/bash

echo "Checking Harmony versions..."
CURRENT_VERSION=$(npm list @uhg-harmony/react --depth=0 | grep @uhg-harmony/react | awk '{print $2}' | tr -d '@')
echo "Current version: $CURRENT_VERSION"

echo "Available versions (5+ days old):"
npm view @uhg-harmony/react time | tail -10

echo "To update, run:"
echo "npm install @uhg-harmony/react@<version>"

Make executable: chmod +x scripts/update-harmony.sh

Version Update Workflow

Pre-Update Assessment

1. Review current project stability
2. Check if update is necessary (bug fix, new feature, security)
3. Review Harmony release notes
4. Identify breaking changes
5. Allocate time for testing

Update Execution

# 1. Backup current state
git checkout -b harmony-update-$(date +%Y%m%d)

# 2. Check available versions
npm view @uhg-harmony/react time | tail -20

# 3. Update package.json
# Edit package.json with new versions

# 4. Clean install
rm -rf node_modules package-lock.json
npm install

# 5. Build and test
npm run build
npm run dev

# 6. Run tests (if available)
npm test

# 7. Visual regression testing
# Test all pages/components using Harmony

# 8. Commit changes
git add package.json package-lock.json
git commit -m "chore: update Harmony packages to v1.2.5"

Post-Update Validation

• Application builds without errors
• Application runs without console errors
• All Harmony components render correctly
• No visual regressions
• Accessibility still maintained
• Performance unchanged or improved

Rollback Procedure

If issues arise after update:

# 1. Revert changes
git revert HEAD

# 2. Or checkout previous state
git checkout main
git branch -D harmony-update-$(date +%Y%m%d)

# 3. Reinstall previous versions
rm -rf node_modules package-lock.json
npm install

Best Practices

1. Version Pinning: Use exact versions in package.json for Harmony packages
2. Synchronized Updates: Update all Harmony packages to the same version
3. Test Thoroughly: Test all components and pages after updating
4. Document Changes: Keep track of which version works in your environment
5. Gradual Rollout: Update in development → staging → production
6. Monitor: Watch for console warnings and runtime errors

Emergency Support

If you encounter critical issues:

1. Teams Channel: Post in Harmony Support
2. GitHub Issues: Open issue at https://github.com/OptumInsight-Platform/harmony/issues
3. Rollback: Use rollback procedure above
4. Document: Record the issue for future reference