Skip to content

VDL Release Playbook

This playbook covers the supported release path for: - PyPI packages published from GitLab CI - standalone macOS binaries built locally on macOS - standalone Windows binaries built locally on Windows - a shared release.json manifest published to GitLab Pages

Release Model

The installer is also the updater.

That means every published release must preserve this contract: - install is safe to rerun - dependency checks happen before binaries are replaced - same-version installs are a no-op unless forced - newer installed versions are preserved unless forced - failed replacement restores the previous binaries - user data is never touched by install or update

The release manifest is the installer source of truth for: - latest version - per-platform asset URL - per-platform checksum - per-platform required commands and install hints

Prerequisites

One-time local setup: - Python 3.13 - uv - glab authenticated for this project - working ffmpeg and ffprobe on the build machine

Platform-specific build machines: - macOS arm64 for aarch64-apple-darwin - Windows x86_64 for x86_64-pc-windows-msvc

GitLab / PyPI setup: - PyPI Trusted Publishing configured for project vdl - GitLab environment named pypi - GitLab CI/CD variables for optional CI binary lanes as needed

Fast Paths

macOS full release:

task release

macOS non-interactive:

task release:yes

Windows binary build:

task build:windows

Windows release asset upload:

task release:upload-windows

1. Preflight

Before tagging any release:

task release:preflight

That preflight should confirm: - tests pass - docs build cleanly - the PyPI package builds - the current pyproject.toml version is newer than the latest GitLab release/tag

The version gate is mandatory. If the latest GitLab release/tag is equal to or newer than pyproject.toml, bump the version first.

2. Build the Release Artifacts

macOS

task build:macos

Expected outputs: - out/vdl-<version>-aarch64-apple-darwin.tar.gz - out/SHA256SUMS

Windows

task build:windows

Expected outputs: - out/vdl-<version>-x86_64-pc-windows-msvc.zip - out/vdl-<version>-x86_64-pc-windows-msvc.zip.sha256

The Windows archive must contain: - vdl.exe - vdl-mcp.exe

3. Tag and Push

VERSION="$(awk -F'"' '/^version/ {print $2; exit}' pyproject.toml)"
git tag "vdl-v${VERSION}"
git push origin "vdl-v${VERSION}"

GitLab CI then handles: - test jobs - wheel/sdist build - PyPI publish - Pages publish after release assets exist

4. Upload Binary Assets to the GitLab Release

macOS:

task release:upload-macos

Windows:

task release:upload-windows

The release assets are what vdl-publish-pages uses to generate the installer manifest.

5. Publish Pages and Refresh release.json

After the release assets exist, run or trigger the vdl-publish-pages job.

That job publishes: - the documentation site - install.sh - install.ps1 - stable/release.json

The manifest now includes: - version - platforms - url - sha256 - required_commands

Example shape:

{
  "version": "2.0.0",
  "platforms": {
    "x86_64-pc-windows-msvc": {
      "url": "https://...",
      "sha256": "...",
      "required_commands": [
        {
          "name": "ffmpeg",
          "command": "ffmpeg",
          "install_hint": "winget install -e --id Gyan.FFmpeg"
        }
      ]
    }
  }
}

6. Smoke Test the Published Installers

macOS / Linux

curl -fsSL https://bildcraft.gitlab.io/products/video-downloader/vdl/install.sh | sh
~/.local/bin/vdl --version
~/.local/bin/vdl doctor

Windows

irm https://bildcraft.gitlab.io/products/video-downloader/vdl/install.ps1 | iex
& "$env:USERPROFILE\.local\bin\vdl.exe" --version
& "$env:USERPROFILE\.local\bin\vdl.exe" doctor

Installer expectations: - detect the currently managed install - install latest if missing - no-op if already current - update if older - stop if the installed version is newer unless forced - check required dependencies before replacing binaries - restore the previous binaries if final smoke checks fail - never remove downloads, config, state, logs, or cache

Supported Installer Flags

macOS / Linux: - --install-deps - --yes - --force - --version <value>

Windows: - -InstallDeps - -Yes - -Force - -Version <value>

Current Platform Scope

Published standalone installer targets: - aarch64-apple-darwin - x86_64-unknown-linux-gnu - x86_64-pc-windows-msvc

The release manifest may omit any platform whose asset was not uploaded for that version.

Uninstall

Uninstall removes only managed binaries.

macOS / Linux:

rm -f ~/.local/bin/vdl ~/.local/bin/vdl-mcp

Windows:

Remove-Item "$env:USERPROFILE\.local\bin\vdl.exe" -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.local\bin\vdl-mcp.exe" -ErrorAction SilentlyContinue

User data stays in place unless you remove it separately.

Yanking a Bad Release

glab release delete "vdl-v${VERSION}"
git push --delete origin "vdl-v${VERSION}"
git tag -d "vdl-v${VERSION}"

After yanking: - bump the version - rebuild the affected artifacts - republish the release assets - rerun Pages so the manifest reflects the corrected release