Road to v1.0

This page explains how FlaUI for Python gets from where it is today to a stable v1.0.0 on PyPI, how you can help by testing beta releases, and how the documentation is versioned so the docs you read always match the package you installed.

For the feature-level checklist see the Roadmap; this page is about releasing.

Why a fresh 1.0

The last published release on PyPI is several years old and was a thin, experimental layer. The current codebase is effectively a ground-up rewrite: Pydantic-backed models, a 1:1 FlaUI surface (elements, patterns, events, capturing), UIA2/UIA3 facades, and a typed, Pythonic API. Because of that, 0.x and 1.x are not API-compatible — see the Upgrade guide before migrating.

Release stages

graph LR
  A[Complete Phase 0 + Phase 6] --> B[Beta releases on PyPI]
  B --> C[Community soak & feedback]
  C --> D[Stable v1.0.0]
  D --> E[stable docs alias]

1. Finish the intended scope — close out Phase 0 — Stabilize (green CI + coverage gate) and the Phase 6 enhancers (context managers, collections, expect(), py.typed + ty).
2. Publish betas to PyPI — cut 1.0.0bN pre-releases so users can try the new API on real apps without it becoming the default pip install.
3. Soak & gather feedback — triage issues against the v1.0 milestones; iterate on betas as needed.
4. Promote to stable v1.0.0 — once the betas are clean, publish the stable release and make stable the default documentation version.

Testing a beta release

Pre-releases are not installed by default. Opt in explicitly:

uv pip install --prerelease=allow flaui-uiautomation-wrapper

pip install --pre --upgrade flaui-uiautomation-wrapper

Pin an exact beta when you want reproducibility:

pip install flaui-uiautomation-wrapper==1.0.0b1

Please report anything surprising on the issue tracker — beta feedback is the whole point of this stage.

How releases are automated

Releases are tag-driven, which sidesteps the protected-master problem (no workflow needs to push commits to master):

PyPI publishing runs entirely on GitHub Actions using the repository PYPI_API_TOKEN / TEST_PYPI_API_TOKEN secrets. publish-pypi.yml is the single PyPI publish path (it builds the package at a tag and uploads it); publish-testpypi.yml handles pull-request dev builds.

Betas are minted and published automatically on merge; the stable release is the one human checkpoint — nothing stable reaches PyPI until you publish the reviewed draft from GitHub Releases. Uploads use skip-existing, so re-runs are idempotent.

Each GitHub release links back to its PyPI version and the docs site (see .github/release-drafter.yml).

Changelog page

The Changelog is generated at docs build time by scripts/build_changelog.py, which fetches published GitHub Releases (betas and stable) and renders their notes into a single page. It is gitignored and refreshes on every docs build, so it always matches GitHub Releases without manual upkeep. The fetch is build-safe: if the GitHub API is unreachable (offline local builds, rate limits) a small fallback page is written instead so the strict build never fails.

Documentation versioning

The docs site is versioned so that each release has its own snapshot. Versioning uses mike (Zensical's fork) and is enabled in zensical.toml:

[project.extra.version]
provider = "mike"
alias = true

Versions are published as subdirectories of the site, with two moving aliases:

Until v1.0.0 ships, latest is the default landing version. When 1.0.0 is released, stable is set as the default so first-time visitors see released docs.

Maintainer workflow

pip install git+https://github.com/squidfunk/mike.git

Build the static site, then deploy it under a version + alias (run from the repo root):

# Build the current docs
uv run python scripts/extract_versions.py
uv run zensical build -f zensical.toml

# Deploy in-development docs as the `latest` alias
mike deploy --push --update-aliases dev latest

# On a release, deploy the version and move the `stable` alias
mike deploy --push --update-aliases 1.0.0 stable

# At v1.0.0, make `stable` the landing version
mike set-default --push stable

Each mike deploy commits to the gh-pages branch; --push publishes immediately.

Automated deployment (CI)

The Azure Pipelines deploy_docs stage publishes versioned docs with mike automatically: