Release Checklist

ReplayLab v0.1.0a4 is published as a GitHub public-alpha prerelease:

https://github.com/Symblee/ReplayLab/releases/tag/v0.1.0a4

The alpha packages are distributed through both GitHub release assets and PyPI. TestPyPI and PyPI publish verification has also passed for 0.1.0a4.

User Install Flow

Download all v0.1.0a4 assets into one local directory so dependency resolution can find the matching schema package:

uv venv --seed --python 3.13 .venv
source .venv/bin/activate
python -m pip install --find-links ./replaylab-v0.1.0a4 replaylab==0.1.0a4
replaylab version
replaylab doctor --project-name smoke

The asset directory must contain both replaylab and replaylab-schemas for 0.1.0a4.

PyPI Install Flow

Install the public-alpha package from PyPI:

uv venv --seed --python 3.13 .venv
source .venv/bin/activate
python -m pip install replaylab==0.1.0a4
replaylab version
replaylab doctor --project-name smoke

Because 0.1.0a4 is the latest published ReplayLab version, python -m pip install replaylab also installs the alpha. Pin replaylab==0.1.0a4 in reproducible docs and smoke checks.

Published package pages:

• https://pypi.org/project/replaylab/
• https://pypi.org/project/replaylab-schemas/

Future Release-Candidate Install Flow

For an unpublished future candidate, build the local release-candidate wheelhouse:

python scripts/release_rehearsal.py --channel github --version <next-version>

Install from that local wheelhouse in a clean environment:

uv venv --seed --python 3.13 .venv
source .venv/bin/activate
python -m pip install --find-links ./dist/public-alpha/v<next-version> replaylab==<next-version>
replaylab version
replaylab doctor --project-name smoke
replaylab app --help
replaylab workflow local --help

This validates the candidate users would receive later. It does not publish the package.

Run package-installing scenarios against the same local wheelhouse:

python scripts/run_scenario.py run support-bot-demo-local --keep-workspace \
  --package-version <next-version> \
  --package-wheelhouse dist/public-alpha/v<next-version>
python scripts/run_scenario.py run pydantic-ai-local --keep-workspace \
  --package-version <next-version> \
  --package-wheelhouse dist/public-alpha/v<next-version>
python scripts/run_scenario.py run local-app-workflow --keep-workspace \
  --package-version <next-version> \
  --package-wheelhouse dist/public-alpha/v<next-version>

Package Index Publishing

PyPI/TestPyPI publishing uses GitHub trusted publishers, not long-lived package-index tokens. Configure these pending publishers before running the manual workflow:

Site	Project	GitHub environment
TestPyPI	replaylab-schemas	testpypi-schemas
TestPyPI	replaylab	testpypi-replaylab
PyPI	replaylab-schemas	pypi-schemas
PyPI	replaylab	pypi-replaylab

For a future candidate, publish to TestPyPI first only after release-candidate validation is green and a separate publish task is approved:

gh workflow run publish.yml -f target=testpypi -f version=<next-version>
gh run watch --exit-status

Verify TestPyPI from a clean Python 3.13 virtual environment:

uv venv --seed --python 3.13 .venv
source .venv/bin/activate
python -m pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  replaylab==<next-version>
replaylab version
replaylab doctor --project-name smoke

Only after TestPyPI succeeds, publish the future version to PyPI:

gh workflow run publish.yml -f target=pypi -f version=<next-version>
gh run watch --exit-status

Verify PyPI from a clean Python 3.13 virtual environment:

uv venv --seed --python 3.13 .venv
source .venv/bin/activate
python -m pip install replaylab==<next-version>
replaylab version
replaylab doctor --project-name smoke

PyPI file uploads are immutable for a package version. If a package-index publish is wrong, fix forward with a later version; after 0.1.0a4 that would be 0.1.0a5. Do not expect to overwrite an already-published version.

Maintainer Candidate Checks

Before any future release candidate, run the standard quality gates:

uv sync --all-packages --all-groups
uv run --all-packages --all-groups ruff format --check .
uv run --all-packages --all-groups ruff check .
uv run --all-packages --all-groups mypy packages services tests examples
uv run --all-packages --all-groups pyright
uv run --all-packages --all-groups mkdocs build --strict
uv run --all-packages --all-groups pytest tests/unit tests/integration tests/e2e --cov=packages --cov=services --cov-report=term-missing --cov-fail-under=95
git diff --check

Build and smoke-install the public packages:

python scripts/release_smoke.py

Build and verify the committed React product app and fallback viewer assets before a package release:

npm ci --prefix apps/web
npm run lint --prefix apps/web
npm run typecheck --prefix apps/web
npm run test --prefix apps/web
npm run build --prefix apps/web
python scripts/build_local_viewer.py --check

The release smoke verifies the installed wheel contains app_static/replaylab-app.js, app_static/replaylab-app.css, viewer_static/replaylab-viewer.js, viewer_static/replaylab-viewer.css, lifecycle adapter imports, report viewer commands, replaylab report diff-explain --help, replaylab ai plan-instrumentation --help, and replaylab report export-viewer --help, replaylab report view --help, replaylab workflow local --help, and replaylab app --help.

Run a real OpenAI dogfood check when a maintainer key is available in .env.local. The script installs the current published replaylab package from PyPI in a temporary environment, makes one real Responses capture call, then replays and runs the generated pytest provider replay guard with an invalid API key to prove ReplayLab serves the recorded response locally.

python scripts/real_openai_dogfood.py --keep-workspace

The script never prints OPENAI_API_KEY. Set REPLAYLAB_DOGFOOD_OPENAI_MODEL in .env.local or pass --model to override the default low-cost model candidates.

Run a real HTTP dogfood check to validate installed requests, sync httpx, and async httpx against a deterministic loopback server:

python scripts/real_http_dogfood.py --keep-workspace

The script starts the loopback server only for capture, then shuts it down before replay and the generated pytest provider replay guard. A missed ReplayLab interception therefore fails with a connection error instead of silently calling a live HTTP dependency.

Run the scenario harness to validate the same workflows through the scenario registry:

python scripts/run_scenario.py list
python scripts/run_scenario.py run no-key-dogfood
python scripts/run_scenario.py run new-user-pypi-local --keep-workspace --package-version 0.1.0a4
python scripts/run_scenario.py run support-bot-demo-local --keep-workspace --package-version 0.1.0a4
python scripts/run_scenario.py run http-loopback-pypi --keep-workspace --package-version 0.1.0a4
python scripts/run_scenario.py run http-edge-cases-local --keep-workspace
python scripts/run_scenario.py run auto-instrumentation-local --keep-workspace
python scripts/run_scenario.py run asgi-fastapi-local --keep-workspace
python scripts/run_scenario.py run asgi-lifecycle-local --keep-workspace
python scripts/run_scenario.py run job-worker-local --keep-workspace
python scripts/run_scenario.py run job-lifecycle-local --keep-workspace
python scripts/run_scenario.py run pydantic-ai-local --keep-workspace
python scripts/run_scenario.py run langgraph-local --keep-workspace
python scripts/run_scenario.py run ai-diagnosis-loopback --keep-workspace
python scripts/run_scenario.py run html-report-local --keep-workspace
python scripts/run_scenario.py run html-report-failure-local --keep-workspace
python scripts/run_scenario.py run react-viewer-local --keep-workspace
python scripts/run_scenario.py run viewer-first-local --keep-workspace
python scripts/run_scenario.py run guided-local-workflow --keep-workspace
python scripts/run_scenario.py run local-app-shell --keep-workspace
python scripts/run_scenario.py run local-app-workflow --keep-workspace
python scripts/run_scenario.py run failure-story-local --keep-workspace
python scripts/run_scenario.py run openai-real-pypi --paid --keep-workspace --package-version 0.1.0a4

The no-key scenario is deterministic and safe for normal CI. Pin published-package scenarios with --package-version 0.1.0a4 during post-release confidence checks so the evidence names the exact public alpha under test. The new-user PyPI scenario validates the first-project onboarding loop with one requests call, viewer export, generated pytest, and no provider credentials. The support-bot demo scenario validates the customer-facing story with OpenAI plus HTTP loopback providers, clean and failed React viewers, report diff, generated pytest, and no secrets. Before a future package release, open that kept workspace with the current checkout's replaylab app to verify the app-first demo flow still starts from latest artifacts and recovers command/provider defaults. The HTTP loopback scenarios use real installed clients and local sockets; http-edge-cases-local validates the current checkout before a future alpha release, while http-loopback-pypi validates the published package. The ASGI/FastAPI scenario validates request-scoped middleware capture in a clean local install. The richer ASGI lifecycle scenario also checks ignored paths, provider-free requests, safe request metadata, and authorization/cookie redaction. The auto-instrumentation scenario validates the low-boilerplate "auto" provider selection and instrument_app(...) helper. The worker/job scenario validates decorator-based job capture in a clean local install. The richer job lifecycle scenario also checks provider-free jobs, sync and async job invocations, positional and keyword session-ID extraction, and per-job generated regressions. The PydanticAI and LangGraph compatibility scenarios validate popular agent-framework shapes through provider-level capture and replay, without making those frameworks hard ReplayLab dependencies. The PydanticAI scenario covers OpenAI Responses through OpenAIResponsesModel; the LangGraph scenario covers StateGraph node work with requests and OpenAI Responses. The AI diagnosis scenario uses a loopback OpenAI-compatible endpoint so advisory report explanation, report-diff explanation, and instrumentation-planning commands can be validated without an external model call. The HTML report scenario exports a clean replay report into a static local viewer and checks that no payload bodies are rendered. The HTML failure scenario intentionally creates a mismatched replay, exports failure HTML and diff HTML, and checks that the static fallback surfaces expected-vs-actual diagnostics without payload bodies. The React viewer scenario exports clean, failed, and diff viewer files, then checks diagnosis panels, quick filters, grouped next commands, diff labels, and secret safety. The local app shell scenario starts replaylab app, queries its localhost APIs, verifies capsule and report discovery, role-labeled and deduplicated start-point shortcuts, command recovery hints, workflow defaults, and checks diagnosis data stays secret-safe. The local app workflow scenario then uses the token-protected product endpoint POST /api/workflows/replay to run clean and failed replay workflows from the app path. The legacy POST /api/workflows/local alias remains during migration. The scenario checks artifact-derived provider defaults, viewer export, optional pytest generation, and no placeholder app-command snippets. The failure-story scenario intentionally creates a mismatched replay and verifies CLI report inspection, React viewer export, static HTML export, and the local app API all present the same first-divergence story with expected-vs-actual evidence before tables. The OpenAI scenario is paid and must stay explicit.

For a future release candidate, build the exact GitHub prerelease wheelhouse, generate checksums and release notes, and install-smoke from the local release directory:

python scripts/release_rehearsal.py --channel github --version <next-version>

The rehearsal writes:

dist/public-alpha/v<next-version>/
  replaylab-<next-version>-py3-none-any.whl
  replaylab-<next-version>.tar.gz
  replaylab_schemas-<next-version>-py3-none-any.whl
  replaylab_schemas-<next-version>.tar.gz
  release-manifest.json
  release-notes.md

The rehearsal prints the exact draft GitHub prerelease command. Do not run that command, create a tag, or publish package-index artifacts as part of release-candidate prep.

GitHub Prerelease Verification

For the live v0.1.0a4 prerelease, verification covered:

• gh release view v0.1.0a4 shows a non-draft prerelease.
• Release assets include both packages' wheels and sdists plus release-manifest.json.
• Downloaded asset SHA-256 hashes match the manifest.
• A clean Python 3.13 virtualenv installs replaylab==0.1.0a4 from the downloaded asset directory.
• replaylab version and replaylab doctor --project-name smoke succeed from the installed wheel.

Package Index Verification

For the live 0.1.0a4 package-index publication, verification covered:

• The manual publish workflow succeeded with target=testpypi.
• A clean Python 3.13 virtual environment installed replaylab==0.1.0a4 from TestPyPI with third-party dependencies resolved from PyPI.
• The manual publish workflow succeeded with target=pypi.
• https://pypi.org/pypi/replaylab/json and https://pypi.org/pypi/replaylab-schemas/json return 200.
• A clean Python 3.13 virtual environment installed replaylab==0.1.0a4 from PyPI.
• A clean Python 3.13 virtual environment installed unpinned replaylab from PyPI and resolved to 0.1.0a4.
• replaylab version and replaylab doctor --project-name smoke succeed from the PyPI install.
• replaylab report export-viewer --help, replaylab report view --help, replaylab app --help, replaylab report diff-explain --help, and replaylab ai plan-instrumentation --help succeed from both pinned and unpinned PyPI installs.
• Post-release confidence validation ran no-key-dogfood, http-loopback-pypi --package-version 0.1.0a4, support-bot-demo-local --package-version 0.1.0a4, and pydantic-ai-local --package-version 0.1.0a4. Paid OpenAI confidence remains a separate post-release check.

GitHub Verification

After pushing release docs or status updates, check GitHub Actions:

gh run list
gh run watch --exit-status

The CI workflow must pass the Python quality matrix, the package smoke job, and the GitHub public-alpha release rehearsal job. The Docs workflow must build and deploy the MkDocs site.

Future Work

• Package signing or provenance attestation.
• Cloud upload, hosted issue grouping, or web UI launch.