1  # PowerToys Update Process
  2  
  3  This document describes how the PowerToys update mechanism works.
  4  
  5  ## Key Files
  6  
  7  - `updating.h` and `updating.cpp` in common - Contains code for handling updates and helper functions
  8  - `update_state.h` and `update_state.cpp` - Handles loading and saving of update state
  9  
 10  ## Update Process
 11  
 12  ### Version Detection
 13  - Uses GitHub API to get the latest version information
 14  - API returns JSON with release information including version and assets
 15  - Checks asset names to find the correct installer based on:
 16    - Architecture (ARM64 or X64)
 17    - Installation scope (user or machine)
 18  
 19  ### Installation Scope
 20  - Differentiates between user installer and machine installer
 21  - Different patterns are defined to distinguish between the two scopes
 22  - Both have different upgrade codes
 23  
 24  ### Update State
 25  - State is stored in a local file
 26  - Contains information like:
 27    - Current update state
 28    - Release page URL
 29    - Last time check was performed
 30    - Whether a new version is available
 31    - Whether installer is already downloaded
 32  
 33  ### Update Checking
 34  - Manual check: When user clicks "Check for Updates" in settings
 35  - Automatic check: Periodic update worker runs periodically to check for updates
 36  - Update state is saved to: `%LOCALAPPDATA%\Microsoft\PowerToys\update_state.json`
 37  
 38  ### Update Process Flow
 39  1. Check current version against latest version from GitHub
 40  2. If newer version exists:
 41     - Check metered connection settings
 42     - Check if automatic updates are enabled
 43     - Check GPO settings
 44  3. Process new version:
 45     - Check if installer is already downloaded
 46     - Clean up old installer files
 47     - Download new installer if needed
 48  4. Notify user via toast notification
 49  
 50  ### PowerToys Updater
 51  - `PowerToysUpdate.exe` - Executable shipped with installer
 52  - Handles downloading and running the installer
 53  - Called when user clicks the update toast notification
 54  - Downloads the installer if not already downloaded
 55  
 56  ### Version Numbering
 57  - Semantic versioning: `MAJOR.MINOR.PATCH`
 58  - MINOR version increases with regular releases (e.g., 0.89.0)
 59  - PATCH version increases for hotfixes (e.g., 0.87.0 → 0.87.1)
 60  
 61  ### Installer Details
 62  - Uses WiX bootstrapper
 63  - Defines upgrade codes for per-user and per-machine installations
 64  - These codes must remain consistent for proper updating
 65  
 66  ## GPO Update Settings
 67  
 68  PowerToys respects Group Policy settings for controlling updates:
 69  
 70  - `disable automatic update download` - Prevents automatic downloading
 71  - `disable new update toast` - Controls if toast notifications are shown
 72  - `suspend new update toast` - Suspends toast notifications for 2 minor releases
 73  
 74  ## User Settings
 75  
 76  Users can control update behavior through the PowerToys settings:
 77  
 78  - Automatic update downloads can be enabled/disabled
 79  - Download and install updates automatically on metered connections
 80  
 81  ## Update Notification
 82  
 83  When a new update is available:
 84  1. Toast notification appears in the Windows Action Center
 85  2. Clicking the notification starts the update process
 86  3. The updater downloads the installer (if not already downloaded)
 87  4. The installer runs with appropriate command-line arguments
 88  
 89  ## Debugging Tips
 90  
 91  ### Testing Update Detection
 92  - To force an update check, modify the timestamp in the update state file to an earlier date
 93  - Exit PowerToys, modify the file, then restart PowerToys
 94  
 95  ### Common Issues
 96  - Permission issues can prevent downloading updates
 97  - Network connectivity problems may interrupt downloads
 98  - Group Policy settings may block updates
 99  - Installer may fail if the application is running
100  
101  ### Update Logs
102  - Check PowerToys logs for update-related messages
103  - `%LOCALAPPDATA%\Microsoft\PowerToys\Logs\PowerToys-*.log`
104  - Look for entries related to update checking and downloading
105  
106  ## Rollout Considerations
107  
108  - Updates are made available to all users simultaneously
109  - No staged rollout mechanism is currently implemented
110  - Critical issues discovered after release require a hotfix
111  - See [Release Process](release-process.md) for details on creating hotfixes