# Release checklist

This checklist is the current pre-installer gate for a desktop build.

## Required checks

Run from `program/`:

```powershell
.\.venv\Scripts\python.exe tools\release_check.py
```

The command validates package data, runs unit tests, runs integration golden fixtures, and compiles application modules.

## Optional PyInstaller build

Run from `program/` after installing build dependencies:

```powershell
.\.venv\Scripts\python.exe -m pip install -r requirements-build.txt
.\.venv\Scripts\python.exe tools\build_backend_release.py --stop-running
```

This is the preferred day-to-day build because it also stops stale local FotoSoft processes before packaging and copies the hardened backend-enabled config into the produced `dist\OrderScanSorter`.

## Prepare a production profile before packaging

```powershell
.\.venv\Scripts\python.exe tools\prepare_production_profile.py `
  --api-base-url https://api.example.com/api `
  --update-manifest-url https://downloads.example.com/update_manifest_stable.json
Copy-Item config\commercial_settings.release.json config\commercial_settings.json -Force
```

This keeps the local development config untouched until the final release packaging step.

## Build a backend-enabled desktop release

Use this command when you need a build that logs in through the production backend and should not fall back to a local `backend_disabled` config:

```powershell
.\.venv\Scripts\python.exe tools\build_backend_release.py --stop-running
```

The helper:

- temporarily swaps in `config\commercial_settings.release.json`
- runs `PyInstaller` with `OrderScanSorter.spec`
- copies the backend-enabled config into `dist\OrderScanSorter\config\commercial_settings.json`
- restores the working local `config\commercial_settings.json`

After the build, verify:

```powershell
Get-Content dist\OrderScanSorter\config\commercial_settings.json
```

Expected release values:

- `"backend_enabled": true`
- `"release_mode": true`
- non-empty `"api_base_url"`

Future hardening prep artifacts:

- `docs/next-hardening-wave.md`
- `config/transport_pinning.production.template.json`
- `..\deploy\CODE_SIGNING.template.md`
- `..\deploy\TRANSPORT_PINNING.template.md`
- `..\deploy\NUITKA_EVALUATION.template.md`

## Verify an existing build

```powershell
.\.venv\Scripts\python.exe tools\release_check.py --verify-dist dist\OrderScanSorter
```

This checks the packaged executable, required runtime files, and absence of local machine state in the build output.

## Create a release archive

```powershell
.\.venv\Scripts\python.exe tools\package_release.py --version 2026.04.22 --archive-base-url https://fotosoft.pro
```

This creates `release/OrderScanSorter-<version>.zip` and `release/release_manifest.json` from a verified `dist\OrderScanSorter`.

## Create an offline installer bundle

```powershell
.\.venv\Scripts\python.exe tools\package_installer.py --version 2026.04.22
```

This creates `installer/OrderScanSorter-Installer-<version>/` with the release zip, manifests, `install_order_scan_sorter.cmd`, and `INSTALL_INSTRUCTIONS.txt`.

## Prepare a staged update install

```powershell
.\.venv\Scripts\python.exe tools\prepare_update_install.py --archive release\OrderScanSorter-2026.04.22.zip --install-dir dist\OrderScanSorter
```

This unpacks the downloaded archive into a staging folder and creates `apply_update.cmd` plus instructions for applying the update after the running app is closed.

## Package data rules

- Include default business profiles from `profiles/default`.
- Include baseline config files from `config`.
- Include commercial/backend contract docs from `docs`.
- Do not include local commercial state such as `config/device_identity.json`.
- Do not include cached licenses such as `config/offline_license_cache.json`.

## Current dependency gap

The local venv used during development may not include GUI/media/build dependencies. In that case media golden tests are skipped by dependency guards, and `--build` requires installing `PyInstaller`.

## Current workstation note

On the current Windows workstation, `tools\release_check.py --build` may be interrupted by a spurious console `KeyboardInterrupt` even when the user does not press `Ctrl+C`. If that happens, use the staged release flow instead:

```powershell
.\.venv\Scripts\python.exe tools\release_check.py --manifest-only
.\.venv\Scripts\python.exe tools\build_backend_release.py --stop-running
.\.venv\Scripts\python.exe tools\release_check.py --verify-dist dist\OrderScanSorter
.\.venv\Scripts\python.exe tools\package_release.py --version 2026.04.22 --archive-base-url https://fotosoft.pro
.\.venv\Scripts\python.exe tools\package_installer.py --version 2026.04.22
```

## Publish current release to production

Upload the release archive and update manifest to the live static root:

```powershell
scp E:\fotosorter\program\release\OrderScanSorter-2026.04.22.zip root@222.167.208.227:/opt/fotosoft/site/
scp E:\fotosorter\program\release\update_manifest_stable.json root@222.167.208.227:/opt/fotosoft/site/
```

If the cabinet download UI changed, also upload:

```powershell
scp E:\fotosorter\cabinet.js root@222.167.208.227:/opt/fotosoft/site/
scp E:\fotosorter\cabinet.html root@222.167.208.227:/opt/fotosoft/site/
```
