05. Upgrading SYM - setup-your-mac/Setup-Your-Mac GitHub Wiki

Upgrading SYM

Author: Dan K. Snelson
Published: 26-Apr-2023
Categories: Scripts, Setup Your Mac

A comprehensive guide for upgrading Setup Your Mac (SYM) while preserving customizations.

Author: Dan K. Snelson

Introduction

Setup Your Mac aims to simplify initial device configuration by leveraging swiftDialog and Jamf Pro Policy Custom Events to allow end-users to self-complete Mac setup post-enrollment.

"I'd like to upgrade to the latest version, but there doesn't seem to be an easy way to both use the new features and maintain my customizations."

This guide provides a systematic approach to upgrading your Setup Your Mac script while preserving your customizations.

Release Cycle Understanding

Version Management

Setup Your Mac follows a structured release cycle:

  • Major Releases: Significant feature additions and architecture changes
  • Minor Releases: New features and enhancements
  • Patch Releases: Bug fixes and minor improvements

Tracking Updates

Stay informed about updates through:

  • GitHub Releases: Official release announcements
  • Mac Admins Slack: Community discussions in #setup-your-mac
  • Blog Posts: Detailed explanations of new features
  • Release Notes: Comprehensive change documentation

Pre-Upgrade Preparation

Documentation Review

Before upgrading, review:

  1. Release Notes: Understand what's changed
  2. Breaking Changes: Identify compatibility issues
  3. New Features: Plan for additional capabilities
  4. Deprecations: Note removed or deprecated features

Backup Current Configuration

Always backup your current setup:

# Create backup directory
mkdir -p ~/SYM-Backups/$(date '+%Y-%m-%d')

# Backup current script
cp /path/to/current/Setup-Your-Mac-via-Dialog.bash ~/SYM-Backups/$(date '+%Y-%m-%d')/

# Backup configuration files
cp /path/to/config/*.json ~/SYM-Backups/$(date '+%Y-%m-%d')/

Upgrade Process

Step 1: Download Latest Version

Use the terminal to download the latest script:

# Create timestamped filename
timestamp=$(date '+%Y-%m-%d-%H%M%S')

# Download latest version
curl -o ~/Downloads/Setup-Your-Mac-via-Dialog-$timestamp.bash \
  https://raw.githubusercontent.com/setup-your-mac/Setup-Your-Mac/main/Setup-Your-Mac-via-Dialog.bash

Step 2: Determine Script Version

Check the version of your current and new scripts:

# Check current script version
grep "scriptVersion=" /path/to/current/Setup-Your-Mac-via-Dialog.bash

# Check new script version  
grep "scriptVersion=" ~/Downloads/Setup-Your-Mac-via-Dialog-$timestamp.bash

Step 3: Create Working Copy

Duplicate your current script for comparison:

# Create working directory
mkdir -p ~/SYM-Upgrade-Work

# Copy current script
cp /path/to/current/Setup-Your-Mac-via-Dialog.bash ~/SYM-Upgrade-Work/current-version.bash

# Copy new script
cp ~/Downloads/Setup-Your-Mac-via-Dialog-$timestamp.bash ~/SYM-Upgrade-Work/new-version.bash

Using Visual Studio Code for Comparison

Installation and Setup

  1. Install Visual Studio Code: Download from code.visualstudio.com
  2. Install Extensions: Consider the "Bash Debug" and "Shell-format" extensions
  3. Configure Diff View: Set up side-by-side comparison

File Comparison Process

# Open both files in VS Code for comparison
code --diff ~/SYM-Upgrade-Work/current-version.bash ~/SYM-Upgrade-Work/new-version.bash

Identifying Changes

Focus on these areas when comparing:

  1. Configuration Variables: Look for new or changed variables
  2. Function Definitions: Identify new or modified functions
  3. Error Handling: Review improved error management
  4. User Interface: Check for dialog improvements
  5. Policy Handling: Examine policy execution changes

Merging Customizations

Systematic Approach

  1. Identify Customizations: Document all your current customizations
  2. Map to New Version: Find corresponding sections in the new script
  3. Test Compatibility: Ensure customizations work with new features
  4. Update Syntax: Adapt to any syntax changes

Common Customization Areas

Branding Elements

# Example: Custom organization name
organizationName="Your Organization"
organizationLogo="/path/to/logo.png"

Policy Configuration

# Example: Custom policy array
policyArray=(
    "policy1,Application 1,/Applications/App1.app,icon1.png"
    "policy2,Application 2,/Applications/App2.app,icon2.png"
)

User Interface Customization

# Example: Custom dialog settings
welcomeDialogType="userInput"
welcomeDialogTitle="Welcome to Your New Mac"

Testing Merged Configuration

Always test your merged configuration:

# Test in dry-run mode first
sudo bash ~/SYM-Upgrade-Work/merged-version.bash --dry-run

# Test with minimal configuration
sudo bash ~/SYM-Upgrade-Work/merged-version.bash --minimal

Validation and Testing

Pre-Production Testing

  1. Syntax Validation: Check for bash syntax errors
  2. Dry-run Testing: Test without executing policies
  3. Sandbox Testing: Test in isolated environment
  4. User Experience Testing: Review from end-user perspective

Testing Commands

# Validate bash syntax
bash -n ~/SYM-Upgrade-Work/merged-version.bash

# Test script execution (dry-run)
sudo bash ~/SYM-Upgrade-Work/merged-version.bash --dry-run

# Test with verbose logging
sudo bash ~/SYM-Upgrade-Work/merged-version.bash --verbose

Common Issues and Solutions

Issue Solution
Variable naming conflicts Update to new variable names
Function signature changes Adapt function calls
Dialog syntax updates Update dialog commands
Policy structure changes Modify policy definitions

Production Deployment

Staged Rollout

  1. Pilot Group: Deploy to small test group first
  2. Monitor Results: Track success rates and issues
  3. Gradual Expansion: Expand to larger groups
  4. Full Deployment: Roll out to entire organization

Deployment Checklist

  • Backup current production script
  • Update Jamf Pro policy with new script
  • Test policy execution
  • Monitor initial deployments
  • Document any issues encountered
  • Update documentation and procedures

Rollback Plan

Always have a rollback plan:

# Quick rollback to previous version
cp ~/SYM-Backups/$(date '+%Y-%m-%d')/Setup-Your-Mac-via-Dialog.bash /production/path/

# Update Jamf Pro policy to use backup script
# Test rollback functionality
# Communicate rollback to stakeholders

Best Practices

Version Control

Consider using version control for your customizations:

# Initialize git repository
cd ~/SYM-CustomVersions
git init

# Add your customized script
git add Setup-Your-Mac-Custom.bash
git commit -m "Initial custom version"

# Create branches for different environments
git checkout -b development
git checkout -b staging
git checkout -b production

Documentation

Maintain documentation for:

  • Customization Log: Record all changes made
  • Testing Results: Document test outcomes
  • Deployment Notes: Track deployment details
  • Issue Resolution: Document problems and solutions

Regular Maintenance

  • Monthly Reviews: Check for new releases
  • Quarterly Updates: Plan upgrade cycles
  • Annual Audits: Comprehensive review of customizations
  • Continuous Monitoring: Track performance and issues

Resources and Support

Documentation

Community Support

  • Mac Admins Slack: #setup-your-mac channel for community support
  • GitHub Issues: Report bugs and request features
  • MacAdmins.org: Community discussions and resources

Related Resources