Each release gets its own branch releases/X.Y[.Z] and a pull request Release vX.Y into
main. Copy this checklist into the PR description and check off each item. Replace X.Y
throughout with the version.
git checkout -b releases/X.Y main
git push -u origin releases/X.Y
gh pr create --draft --base main --head releases/X.Y --title "Release vX.Y" --body-file RELEASE-PLAN.md-
releases/X.Yexists and the draft PR is open with this checklist as its body.
All release work (optional rehearsal, the release commit, the tag) happens on this branch; it
is merged into main in section 6 and then stays as the hotfix line for X.Y.Z patches.
Where applicable (mark as complete if nothing to update):
-
dist/requirements_windows.txt -
pyproject.toml -
uv lock --upgrade. - update ffmpeg pin (
ffmpeg_version, GyanD/codexffmpeg release name) across all builders - Python version
- Advanced Installer OSS license still valid (
appveyor.ymlresolves the installed Advanced Installer version dynamically, so no path to update)
-
docs/changelog.mdis up to date and accurate -
docs/download.mdis up to date and accurate - Verify all docs are up to date:
README.md,docs/*.md, thedvr-scan.cfgconfig file template,dvr-scan --helpoutput,CONTRIBUTING.md, etc.
-
python scripts/update_installer.pybumpsdist/installer/DVR-Scan.aipfrom__version__:ProductVersion->X.Y, newProductCodeGUID,PackageFileName->dvr-scan-X.Y-win64. Needs Advanced Installer installed locally (setADVINSTto the full path ofAdvancedInstaller.comif it is not underC:\Program Files (x86)\Caphyon). - If bundled files changed (new Python/PyAV/OpenCV DLLs), run
python scripts/update_installer.py --sync-filesafter the local frozen build below to re-syncAPPDIRagainstdist/dvr-scan/. CI re-syncs on every build (--sync-only), so this only keeps the committed.aiprepresentative. Structural changes (dialogs, features, prerequisites, shortcuts, install directory layout) still need the Advanced Installer GUI.
python dist/pre_release.py --release --use-local-images # --release asserts the .aip ProductVersion matches __version__
pyinstaller dist/dvr-scan.spec
python dist/post_release.py
cp ffmpeg.exe dist/dvr-scan/ # the pinned GyanD full_build, not whatever is on PATH
git checkout -- dvr_scan/docs # pre_release.py overwrites the docs, so we must restore it-
dist/dvr-scan/_internal/av.libs/exists with the PyAV FFmpeg DLLs. - From a directory/environment with no ffmpeg on PATH (e.g. a temp dir,
where ffmpegis empty), the following must succeed and produce an mp4 with audio:dvr-scan.exe --version,dvr-scan-app.exe --version,dvr-scan.exe -i <repo>/tests/resources/simple_movement.mp4 -et 5s -df 3(scripts/validate_release.pyrepeats these checks against the final artifacts) -
dvr-scan-app.exelaunches, wizard opens, and can perform a scan
Exercises everything a tag triggers without publishing anything. On releases/X.Y, commit the
release edits with __version__ = "X.Y-rc1" (dates may still be placeholders), then:
git tag vX.Y-rc1-release && git push origin vX.Y-rc1-release-
gh run list --branch vX.Y-rc1-release:Release Tests(tag vs__version__; the changelog heading check is skipped for-rc/-devtags),Python DistributionandWindows Distributionpass;Update Websiteis skipped (its job guard excludes-rc/-devtags). - AppVeyor builds the tag:
.aipre-sync, MSI nameddvr-scan-X.Y-win64.msi(the.aipcarries the stable version, so rc builds produce the stable MSI name/version), SignPath request created. - Approve the SignPath request, download
dvr-scan-signed.zipintodist/signed/, runpython scripts/finalize_windows_dist.py(section 4). - Create a draft pre-release with the eight assets (section 5, add
--prerelease), thengh workflow run release.yml -f tag=vX.Y-rc1-release -f verify-only=true: installer fresh-install + upgrade test (test-installer.ymlmaps rc tags to the stable MSI version) and TestPyPI publish + pip smoke install. - Clean up:
gh release delete vX.Y-rc1-release --yes,git push origin :refs/tags/vX.Y-rc1-release && git tag -d vX.Y-rc1-release, delete the localdist/signed/*and downloaded artifacts. The rc commit stays in the branch history; the TestPyPI upload is harmless.
On releases/X.Y:
-
dvr_scan/__init__.py:__version__ = "X.Y"(no-dev/-rcsuffix). -
docs/changelog.md: heading(In Development)->(YYYY-MM-DD); the heading must be### X.Y (YYYY-MM-DD)(checked byrelease-test.yml). -
README.md:### Latest Release: vX.Y (Month D, YYYY). -
docs/download.md: Python block and Windows blocks need updated version/date information and download links -
docs/index.mdanddocs/index_docs.md:Latest Version: X.Y (Month D, YYYY) -
dist/installer/DVR-Scan.aipif not already committed above - Dates are the actual tag date, consistent across all five files
-
git statusshows nothing else (dvr_scan/docs/is clean)
git add README.md docs/changelog.md docs/download.md docs/index.md docs/index_docs.md \
dvr_scan/__init__.py dist/installer/DVR-Scan.aip
git commit -m "[release] Release vX.Y"git push origin releases/X.Y
git tag vX.Y-release
git push origin vX.Y-release- Tag points at the head of
releases/X.Y(the release commit); the PR's CI is green.
The PR is merged in section 6 with a merge commit or fast-forward, never squash: the tagged
commit must become an ancestor of main.
Pushing the tag triggers Python Distribution, Windows Distribution, Release Tests
(tag vs __version__, changelog heading, twine check, pip-audit), Update Website, and the
AppVeyor build (which re-syncs the .aip file list via scripts/update_installer.py --sync-only
before building the MSI and hands the result to SignPath).
-
gh run list --branch vX.Y-releaseshows all GitHub workflows passing - AppVeyor build passes
- SignPath: approve the signing request and download
dvr-scan-signed.zip(signeddvr-scan.exe,dvr-scan-app.exeand MSI) intodist/signed/. No other inputs are needed: the portable zip is rebuilt from the signed MSI. -
python scripts/finalize_windows_dist.py: verifies the Authenticode signatures, copies the MSI asdvr-scan-X.Y-win64.msi, extracts its file tree withmsiexec /aand repacks it asdvr-scan-X.Y-win64.zipwith 7-Zip, writesdvr-scan-X.Y-win64.manifest.json+SHA256SUMS, then runsscripts/validate_release.py(filenames, hashes, signatures on the MSI and both EXEs inside the zip, MSI/zip parity, frozen-exe smoke tests with ffmpeg removed fromPATH). Re-run the checks alone withpython scripts/validate_release.py. - Portable zip: extract, run
dvr-scan.exe --versionand one scan (also covered by validate).
Installing the MSI on a clean machine (shortcut, dvr-scan --version from a prompt, upgrade over
the previous version, clean uninstall) is automated by test-installer.yml, run in section 6.
- Zenodo: the GitHub switch for
Breakthrough/DVR-Scanis ON before publishing, so the publish event mints a new DOI (the tag itself does not). - Download the Python artifacts from the tag's Python Distribution:
gh run download <run-id> -n dvr-scan-dist -D release/(should be four files:dvr_scan-X.Yanddvr_scan_headless-X.Y,.whl+.tar.gz). - Copy the finalized Windows artifacts from
dist/signed/intorelease/. - Release notes: verbatim to the corresponding the
X.Ychangelog section, but with adjusted####headings promoted to##(#### Release Notes->## Release Notes) since the existing headers are chosen for the website
gh release create vX.Y-release --draft --title "DVR-Scan vX.Y" --notes-file release-notes.md \
release/dvr-scan-X.Y-win64.msi release/dvr-scan-X.Y-win64.zip \
release/dvr-scan-X.Y-win64.manifest.json release/SHA256SUMS \
release/dvr_scan-X.Y-py3-none-any.whl release/dvr_scan-X.Y.tar.gz \
release/dvr_scan_headless-X.Y-py3-none-any.whl release/dvr_scan_headless-X.Y.tar.gz- Eight assets, Windows names exactly as linked from
docs/download.md. Leave the release as a draft; the orchestrator publishes it.
release.yml verifies the draft release's artifacts and then publishes stage by stage:
test-installer.yml (fresh install + upgrade from the previous release on a clean
windows-latest runner) -> TestPyPI publish + pip smoke install -> GitHub release
(draft -> public, marked latest) -> PyPI publish + pip smoke install.
gh workflow run release.yml -f tag=vX.Y-release -f verify-only=true # optional: stop before anything goes public
gh workflow run release.yml -f tag=vX.Y-release
gh run watchpublish-pypi.yml can still be dispatched by hand (-f tag=vX.Y-release -f environment=testpypi|pypi);
for pypi it requires the tag's Python Distribution, Windows Distribution and
Release Tests runs to have succeeded.
- Orchestrator run is green
- https://pypi.org/project/dvr-scan/ and https://pypi.org/project/dvr-scan-headless/ show
X.Y. - Release is public and marked latest; Zenodo record appears at https://zenodo.org/account/settings/github/
- Smoke test using
pip:
python -m venv /tmp/dvr && . /tmp/dvr/bin/activate # or .\Scripts\activate
pip install dvr-scan==X.Y
dvr-scan --version
dvr-scan -i tests/resources/simple_movement.mp4 -so -df 4 -et 100
pip install --force-reinstall dvr-scan-headless==X.Y && dvr-scan --version- Mark the PR ready and merge it into
mainwith a merge commit or fast-forward (not squash) so the tagged commit is an ancestor ofmain. Keepreleases/X.Y.
update-site.yml runs automatically when the vX.Y-release tag is pushed (and on
workflow_dispatch). Because that happens before section 6, the download links on the site
resolve only once the release is public; re-dispatch if the site needs rebuilding later:
gh workflow run update-site.yml --ref vX.Y-release- https://www.dvr-scan.com/ shows
Latest Version: X.Y,/download/links resolve correctly,/changelog/shows the new section at the top
-
dvr_scan/__init__.py:__version__ = "X.(Y+1)-dev0", add### X.(Y+1) (In Development)at the top ofdocs/changelog.md. Commit[dist] Prepare for vX.(Y+1) development - Close the roadmap issue and milestone:
gh issue close <n> -c "Released in vX.Y"; close milestonevX.Yon GitHub. - Close/comment issues fixed in this release that are still open.
-
CITATION.cff: addversion: X.Y,date-released: YYYY-MM-DD, and (first time only) the conceptdoi:; add the DOI badge toREADME.md(snippet inNEXT.md). - Announce: Discord, GitHub Discussions, any issues that asked for the feature.
| Script/Workflow | Description |
|---|---|
scripts/common.py |
version normalization, artifact names, hashing, Authenticode check |
scripts/update_installer.py |
.aip version/GUID/package-name bump; --sync-files / --sync-only [--dev] re-sync APPDIR |
scripts/finalize_windows_dist.py |
signed bundle -> MSI + portable zip + manifest + SHA256SUMS, then validate |
scripts/validate_release.py |
standalone artifact validation (--allow-unsigned for local dry runs) |
dist/pre_release.py --release |
asserts the .aip ProductVersion matches __version__ |
release-test.yml |
tag vs __version__, changelog heading, build + twine check, pip-audit |
test-installer.yml |
MSI fresh install / upgrade / uninstall on a clean runner |
release.yml |
orchestrates installer test -> TestPyPI -> GitHub release -> PyPI (verify-only=true stops before anything goes public) |
update-site.yml |
rebuilds www.dvr-scan.com on v*-release tags |
appveyor.yml |
frozen build, .aip re-sync, MSI build, SignPath hand-off |