Documentation

Operations, Build Automation, and Release Guide (Operation Guide)

Comprehensive runbook for version synchronization, standalone compilation (.exe), and Microsoft Store (MSIX) packaging automation.

End-to-end operational guide for version synchronization, automated compilation, and Windows Store package staging.

This document provides operational instructions for the PowerShell automation scripts that manage fjFlow’s versioning, standalone binary compilation (.exe), and pre-packaging workflows for Windows Store (MSIX) deployments.

Table of Contents

1. Automation Scripts Overview

Release operations are automated via scripts located at the repository root:

Script Purpose & Behavior Key Options
update_version.ps1 Extracts version and changelog from RELEASE_NOTES.txt, syncs variables, and triggers compilation -Build:$true (default) / -Build:$false
build.ps1 Compiles .ahk sources into fjFlow_Free.exe and fjFlow_Pro.exe using Ahk2Exe -Edition "all" (default) / "free" / "pro"
prepare-msix.ps1 Stages compiled binaries into msix_build_free and msix_build_pro packaging folders -Edition "all" (default) / "free" / "pro"
tools/generate_assets.ps1 Automatically converts and generates application and store visual assets None

2. Three-Step Release Workflow

Follow these steps to produce and stage a new software release:

Step 1: Update the Release Notes

  1. Open RELEASE_NOTES.txt in a text editor.
  2. Enter the new version number on the first line, followed by bulleted release highlights:
Version: 1.2.0

- Improved keystroke responsiveness in key extensions
- Added magnifier grid mode to UI Hint navigation
- Resolved layout clipping issues in settings GUI

Step 2: Synchronize Version and Run Automated Compilation

Open a PowerShell terminal and run:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; .\update_version.ps1

What happens:

  1. The script parses the version number (e.g., 1.2.0) from RELEASE_NOTES.txt.
  2. Updates the AppVersion constant in fjFlow.ahk.
  3. Calls build.ps1 to compile both fjFlow_Free.exe and fjFlow_Pro.exe into the build\ folder.

Step 3: Stage the Windows Store (MSIX) Package Directories

Prepare the staging directories required by the MSIX Packaging Tool:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; .\prepare-msix.ps1

What happens:

  • The latest compiled executables from build\ are copied into msix_build_free\ and msix_build_pro\.
  • Directories are ready for packaging via MSIX Packaging Tool or MakeAppx.exe.

3. Script Options and Direct Execution

3.1 update_version.ps1 (Version Synchronization Only)

To update version variables in code without compiling binaries:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; .\update_version.ps1 -Build:$false

3.2 build.ps1 (Individual Edition Compilation)

To compile a single edition independently:

  • Free Edition only: 
    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; .\build.ps1 -Edition free
  • Pro Edition only: 
    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; .\build.ps1 -Edition pro

3.3 prepare-msix.ps1 (MSIX Staging Only)

To prepare only the Pro edition staging folder:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; .\prepare-msix.ps1 -Edition pro

4. Troubleshooting and Operational Standards

4.1 Character Encoding (UTF-8 Without BOM)

  • All scripts and RELEASE_NOTES.txt must be saved in UTF-8 (without BOM).
  • When performing file operations in PowerShell, always specify -Encoding UTF8.

4.2 PowerShell Execution Policy Bypass

  • If execution policy restrictions prevent scripts from running, bypass the policy temporarily: 
    powershell -ExecutionPolicy Bypass -File .\update_version.ps1

4.3 Git Push Protocols

  • Stage and commit build artifacts locally (git add, git commit).
  • Always run git push directly from an interactive terminal to prevent background credential prompt deadlocks.