ChapterForge 1.0.0 - Comprehensive Deployment Guide

This document provides detailed instructions for building, packaging, releasing, and updating ChapterForge 1.0.0 on Windows. This guide covers everything from development environment setup to production deployment strategies.

1. Prerequisites and System Requirements

1.1 Development Environment

ChapterForge 1.0.0 requires the following development environment:

1.2 Hardware Requirements

1.3 Optional Tools for Advanced Deployment

2. Versioning Strategy

ChapterForge 1.0.0 follows Semantic Versioning (SemVer) principles: MAJOR.MINOR.PATCH

2.1 Version Number Components

2.2 Version Update Checklist

When cutting a release, update the version in ALL of these locations:

  1. pyproject.toml → [project] version ``toml [project] name = "chapterforge" version = "1.0.0" # ← Update this ``
  1. chapterforge/__init__.py → __version__ variable ``python __version__ = "1.0.0" # ← Update this ``
  1. installer/ChapterForge.iss → Inno Setup defines ``pascal #define AppVersion "1.0.0" # ← Update this ``
  1. installer/ChapterForge-Portable.iss → Inno Setup defines ``pascal #define AppVersion "1.0.0" # ← Update this ``
  1. CHANGELOG.md → Add new version section with release date ```markdown ## [1.0.0] - 2026-06-06 ### Added

(The PyInstaller spec ChapterForge.spec does not contain a version string, and there is no docs/conf.py - the HTML docs are generated by tools/build_docs.py and pick up the version from chapterforge/__init__.py.)

2.3 Git Tagging Convention

3. Testing and Quality Assurance

3.1 Automated Test Suite

Run the complete test suite before any build or release:

# Run all tests with verbose output
python -m pytest -v

# Run tests with coverage report
python -m pytest --cov=chapterforge --cov-report=html

# Run specific test modules
python -m pytest tests/test_core.py -v
python -m pytest tests/test_cli.py -v
python -m pytest tests/test_ui.py -v

# Run tests in parallel for faster execution
python -m pytest -n auto

3.2 Manual Testing Checklist

Before each release, perform manual testing of:

  1. Installation Process
  1. Core Functionality
  1. Accessibility Features
  1. Advanced Features
  1. Command Line Interface

4. Building ChapterForge 1.0.0

4.1 Development Build

For development and testing purposes:

# Install development dependencies
pip install -r requirements.txt

# Run directly from source
python main.py

# Run CLI version
python cli_main.py --help

# Run background watcher
python main.py --watch

4.2 PyInstaller Build Process

ChapterForge 1.0.0 uses PyInstaller for creating distributable builds:

# Ensure PyInstaller is installed
pip install pyinstaller>=5.0

# Build using the ChapterForge.spec file
pyinstaller ChapterForge.spec

# Build output location
# dist/ChapterForge/ - One-folder build with all dependencies
# ├── ChapterForge.exe        # Graphical application
# ├── chapterforge-cli.exe    # Command-line interface
# ├── _internal/              # Runtime dependencies
# │   ├── python312.dll       # Python runtime
# │   └── ...                 # Other dependencies
# (FFmpeg is NOT bundled - it is downloaded on first run)

PyInstaller Build Options

4.3 Build Customization

Customizing ChapterForge.spec

The ChapterForge.spec file controls the PyInstaller build process. It builds two executables from one spec (the GUI main.py and the console cli_main.py) and shares their dependencies with MERGE. Key points from the actual spec:

# No version string lives in the spec; the version comes from
# chapterforge/__init__.py at runtime.

# Nothing extra is bundled as data - FFmpeg is downloaded at runtime and the
# docs are online, both to keep the build small.
datas = []

hiddenimports = ['wx._xml', 'wx.adv', 'wx.media']
excludes = ['tkinter', 'pytest', 'numpy', 'sympy']

# Two Analysis targets (main.py and cli_main.py), merged so shared
# dependencies are collected once, then COLLECT-ed into dist/ChapterForge/.

Environment Variables for Builds

Set environment variables to customize builds:

# Set build version
set CF_VERSION=1.0.0

# Enable debug logging
set CF_DEBUG=1

# Set custom build paths
set CF_BUILD_DIR=custom_build

# Enable code signing (requires certificate)
set CF_SIGN_BUILD=1

5. Creating Installers

5.1 Standard Installer (Inno Setup)

Create the standard Windows installer:

# Navigate to repository root
cd /path/to/chapterforge

# Ensure PyInstaller build exists
pyinstaller ChapterForge.spec

# Run Inno Setup Compiler
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\ChapterForge.iss

# Output location
# installer_output\ChapterForge-Setup.exe

Inno Setup Script Configuration

Key settings in installer/ChapterForge.iss:

#define AppName "ChapterForge"
#define AppVersion "1.0.0"
#define AppPublisher "Blind Information Technology Solutions (BITS)"
#define AppURL "https://chapterforge.org"
#define AppExeName "ChapterForge.exe"
#define CliExeName "chapterforge-cli.exe"

[Setup]
AppName={#AppName}
AppVersion={#AppVersion}
AppPublisher={#AppPublisher}
AppPublisherURL={#AppURL}
AppSupportURL={#AppURL}
AppUpdatesURL={#AppURL}/updates
DefaultDirName={autopf}\{#AppName}
DefaultGroupName={#AppName}
AllowNoIcons=yes
PrivilegesRequired=admin
OutputBaseFilename={#AppName}-Setup
Compression=lzma2/max
SolidCompression=yes

(The output base filename has no version suffix, so the asset is always ChapterForge-Setup.exe. This keeps the releases/latest/download/... URLs on the website stable across versions.)

5.2 Portable Edition

Create the portable edition with its own Inno Setup script:

# Build PyInstaller one-folder version (shared by both installers)
pyinstaller ChapterForge.spec

# Build the portable installer
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\ChapterForge-Portable.iss

# Output location
# installer_output\ChapterForge-Portable.exe

5.3 Command-Line Tool

There is no separate CLI distribution. The console executable chapterforge-cli.exe is produced by the same ChapterForge.spec build (via PyInstaller MERGE) and ships inside both the standard and portable packages.

6. Code Signing and Security

6.1 Code Signing Process

All official releases must be code-signed:

# Sign executables (requires code signing certificate)
signtool sign /f "certificate.pfx" /p "password" /t "http://timestamp.digicert.com" "dist\ChapterForge\ChapterForge.exe"
signtool sign /f "certificate.pfx" /p "password" /t "http://timestamp.digicert.com" "dist\ChapterForge\chapterforge-cli.exe"

# Verify signatures
signtool verify /pa "dist\ChapterForge\ChapterForge.exe"

6.2 Security Scanning

Perform security scanning before release:

# Run antivirus scan on build output
# Using Windows Defender or other antivirus solution

# Upload to VirusTotal for multi-engine scanning
# https://www.virustotal.com/

# Check for security vulnerabilities in dependencies
pip-audit -r requirements.txt

7. Release Process

7.1 Pre-Release Checklist

Before creating any release:

7.2 Building Official Release

# 1. Clean build environment
git clean -xdf
pip install -r requirements.txt

# 2. Run complete test suite
python -m pytest -v

# 3. Update version numbers to 1.0.0
# (Already done in previous steps)

# 4. Create PyInstaller build
pyinstaller ChapterForge.spec

# 5. Code sign executables
# (As described in Section 6)

# 6. Create installers
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\ChapterForge.iss
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\ChapterForge-Portable.iss

# 7. Verify installers work correctly
# (Manual testing on clean systems)

# 8. Security scan release files
# (VirusTotal and local antivirus)

7.3 GitHub Release Creation

# 1. Create and push Git tag
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# 2. Create the GitHub release. Publishing it triggers the Build Release
#    workflow (.github/workflows/build-release.yml), which builds with
#    PyInstaller + Inno Setup and uploads the two installers automatically.
gh release create v1.0.0 \
  --title "ChapterForge 1.0.0" \
  --notes "Release notes for version 1.0.0"

# To attach the installers manually instead, build them locally and run:
#   gh release upload v1.0.0 \
#     installer_output\ChapterForge-Setup.exe \
#     installer_output\ChapterForge-Portable.exe

7.4 Post-Release Activities

8. Continuous Integration and Deployment

8.1 GitHub Actions Workflow

Example CI/CD workflow in .github/workflows/build.yml:

name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: windows-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.12'
    - name: Install dependencies
      run: |
        pip install -r requirements.txt
        pip install pyinstaller
    - name: Run tests
      run: python -m pytest
    - name: Build application
      run: pyinstaller ChapterForge.spec
    - name: Create installer
      run: |
        "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\ChapterForge.iss
    - name: Upload artifacts
      uses: actions/upload-artifact@v3
      with:
        name: ChapterForge-build
        path: installer_output/

8.2 Automated Testing Matrix

Test on multiple configurations:

9. Update Distribution System

9.1 GitHub Releases Integration

ChapterForge 1.0.0 uses GitHub Releases for update distribution:

  1. Update Check Process:
  1. Automatic Installer Download:

9.2 Update Release Workflow

# 1. Create release notes
# (Update CHANGELOG.md)

# 2. Build and package
# (As described in previous sections)

# 3. Calculate checksums
certutil -hashfile installer_output\ChapterForge-Setup-1.0.0.exe SHA256

# 4. Create GitHub release with assets
gh release create v1.0.0 --generate-notes \
  installer_output\ChapterForge-Setup-1.0.0.exe \
  installer_output\ChapterForge-Portable-1.0.0.zip

# 5. Update latest release pointer
# (Handled automatically by GitHub)

9.3 Downgrade Protection

10. Troubleshooting Common Build Issues

10.1 PyInstaller Issues

Problem: "ImportError: No module named 'xyz'" Solution: Add missing module to ChapterForge.spec hidden imports:

hiddenimports = [
    'missing.module.name',
]

Problem: "Failed to execute script" Solution: Enable console output in spec file for debugging:

console=True

10.2 Inno Setup Issues

Problem: "Cannot find ISCC.exe" Solution: Use full path to Inno Setup compiler:

"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\ChapterForge.iss

Problem: "File not found during compilation" Solution: Verify PyInstaller build completed successfully and files exist in dist/ChapterForge/

10.3 FFmpeg Integration Issues

Problem: "FFmpeg not found at runtime" Solution: Verify FFmpeg binaries are in _internal\bin\ directory after PyInstaller build

Problem: "Unsupported codec or format" Solution: Ensure FFmpeg build includes required codecs and formats

ChapterForge 1.0.0 Deployment Guide - Professional Deployment for Everyone

2. Versioning

ChapterForge follows Semantic Versioning: MAJOR.MINOR.PATCH.

When cutting a release, update the version in all of these places:

The GitHub tag should be vMAJOR.MINOR.PATCH (e.g. v1.0.0).

3. Run the tests

python -m pytest -q

The audio tests synthesize tiny MP3s with FFmpeg and are skipped if FFmpeg is not on PATH. All tests must pass before building a release.

4. Build the executables (PyInstaller)

First, ensure FFmpeg binaries are present (automatically downloaded if missing):

python tools/get_ffmpeg.py

Then generate the HTML help that the app's Help menu opens (the spec bundles docs/html):

python tools/build_docs.py

Then build:

pyinstaller ChapterForge.spec

This produces a one-folder build under dist\ChapterForge\:

The one-folder layout is deliberate: there is no per-launch temp extraction, which avoids the temp-folder cleanup problems of one-file builds when the app closes.

Smoke-test the build before packaging:

dist\ChapterForge\chapterforge-cli.exe "C:\path\to\sample\folder" --list
dist\ChapterForge\ChapterForge.exe

5. Build the installer (Inno Setup)

& "C:\Users\<you>\AppData\Local\Programs\Inno Setup 6\ISCC.exe" installer\ChapterForge.iss

This wraps dist\ChapterForge\ into a single ChapterForge-Setup.exe under the installer's output directory. The installer is per-user (no admin required), creates Start-menu shortcuts for the GUI and adds the CLI to the install folder. Autostart of the watcher is handled in-app (per-user HKCU\…\Run), not by the installer, so the installer needs no elevation.

6. Publish a GitHub Release

  1. Commit and tag: git tag v1.0.0 && git push --tags.
  2. Create a Release for the tag on GitHub.
  3. Attach ChapterForge-Setup.exe as a release asset.
  4. Paste the relevant CHANGELOG.md section as the release notes.

7. The update feed

The in-app Check for Updates feature (chapterforge/updates.py) queries the GitHub Releases API for the configured repository, compares the latest tag to the running version, and points users at the download.

Before the first public release, replace the placeholders in chapterforge/updates.py:

GITHUB_OWNER = "bits-acb"   # -> your GitHub org/user
GITHUB_REPO  = "chapterforge"

Notes on the implementation (adapted from QUILL):

So each release is picked up automatically by existing installs once the tag is published - no separate update server is required.

8. Release checklist