Skip to content

RELEASE_CHECKLIST.md

Latest commit

 

History

History
194 lines (155 loc) · 8.23 KB

RELEASE_CHECKLIST.md

File metadata and controls

194 lines (155 loc) · 8.23 KB
Raw

fp-tools Release Checklist

Use this checklist before publishing fp-tools-bio or preparing paper benchmark artifacts.

1. Environment

  • Use a clean Python 3.12 environment for release orchestration. Wheels target Python 3.11–3.13 on Windows, macOS, and Linux.
  • Confirm editable install:
.venv/bin/python -m pip show fp-tools-bio
.venv/bin/python -m pip check

2. Test Suite

Run the full local test suite:

.venv/bin/python -m pip install pytest
.venv/bin/python -m pytest -q
.venv/bin/python scripts/smoke_console_scripts.py

Required coverage before release:

  • public console scripts
  • YAML config expansion and dry-run behavior
  • command --help smoke checks
  • core-count handling
  • progress logging behavior
  • stable fixture summaries for existing bigWig/BED test data

GitHub Actions must also complete the full pytest suite in the Linux test job and on Windows for Python 3.11, 3.12, and 3.13. Tests that require Linux-only BAM writing or indexing may skip explicitly; collection errors, separator-only failures, and locale-dependent decoding failures are release blockers.

The Windows full suite includes the portable I/O and launcher regressions; do not run those a second time in the same job. Linux/macOS portable-install jobs retain the focused checks because they do not run the full suite. Wheel, frozen-desktop, runtime, container, documentation-browser, and released download checks exercise different artifacts and remain separate release gates.

3. CLI Smoke Checks

Primary current API checks:

.venv/bin/prepare-atac --help
.venv/bin/bulk-footprinting --help
.venv/bin/atac-correct --help
.venv/bin/call-footprints --help
.venv/bin/match-motifs --help
.venv/bin/diff-footprints --help
.venv/bin/normalize-bigwig --help
.venv/bin/plot-aggregate --help
.venv/bin/review-multi-comparisons --help
.venv/bin/run-yaml-workflow --help
.venv/bin/fp-tools-gui --help
.venv/bin/fp-tools-runtime --help
.venv/bin/discover-motifs --help
.venv/bin/summarize-motifs --help
.venv/bin/pseudobulk-fragments --help
.venv/bin/find-signature-fp --help
.venv/bin/sc-footprinting --help
.venv/bin/run-yaml-workflow --config examples/gui_configs/call_footprints_single.yml --dry-run

Platform contract checks:

  • Linux CLI and the Linux container support FASTQ preprocessing through the separate prepare-atac command.
  • bulk-footprinting accepts only BAM/BAI plus peak BED sample tables on every platform. Native macOS and Windows keep prepare-atac --help available but reject execution before downloads or output creation.
  • Every GUI and both desktop bundles accept BAM/BAI plus peak BED inputs and reject prepare-atac, reads_table, and equivalent extra arguments.
  • Non-Linux runtime manifests expose the optional MEME component only; Linux manifests also expose raw-read core and HOMER components.

4. Build Artifacts

Release wheels are built by cibuildwheel in the manual Publish workflow; the two Linux architectures run as separate native jobs. The required artifact set is:

  • CPython 3.11, 3.12, and 3.13
  • Windows AMD64
  • macOS x86_64 and arm64
  • manylinux x86_64 and aarch64

Build an sdist locally only for preflight inspection:

.venv/bin/python -m pip install build twine
.venv/bin/python -m build --sdist
.venv/bin/python -m twine check dist/*

After uploading, verify a fresh install from PyPI:

python -m venv /tmp/fp-tools-pypi-smoke
/tmp/fp-tools-pypi-smoke/bin/python -m pip install --upgrade pip
/tmp/fp-tools-pypi-smoke/bin/python -m pip install --only-binary=:all: "fp-tools-bio==<version>"
/tmp/fp-tools-pypi-smoke/bin/atac-correct --help >/dev/null
/tmp/fp-tools-pypi-smoke/bin/plot-aggregate --help >/dev/null
/tmp/fp-tools-pypi-smoke/bin/fp-tools-gui --help >/dev/null

The Desktop bundles workflow must produce and smoke-test a Windows x64 executable and an unsigned Apple Silicon macOS DMG. Both artifacts must use the fp-tools icon and open the command-backed GUI in a native application window. The live checks verify the private Streamlit server, native window rendering, and frozen child-process dispatch. The Mac job must ad-hoc sign and strictly verify the application bundle, confirm its ARM64 executable, exercise the documented quarantine-removal command, verify and mount the DMG, and confirm that the first-launch instruction is included. Release assets include a SHA-256 checksum manifest. macOS Intel and Linux users install the Python package instead.

The Container workflow builds and tests the complete environment on linux/amd64 and linux/arm64, then attaches both loadable image archives and their checksums to tagged GitHub releases. The publish_version manual input can rebuild archives for an existing version.

The Managed runtimes workflow attaches pinned core, MEME, and HOMER archives for Linux, MEME archives for macOS, and the private Windows MEME WSL2 runtime to the public GitHub release with SHA-256 sidecars. It must verify archive relocation and a real Windows WSL2 import before release handoff. Its publish_version manual input can rebuild archives before repeating the public-consumer smoke.

After the tagged macOS application and managed MEME runtime are both public, dispatch the Release smoke workflow with the published version. It must start from an empty runtime cache and complete STREME, JASPAR-to-MEME conversion, Tomtom, and the packaged motif summarizer twice from the released Apple Silicon application.

The same Release smoke workflow must pass its two isolated Windows public-EXE jobs, with default discovery parameters and explicit STREME extra arguments. Each job verifies the EXE checksum, a fresh managed WSL import, cached reuse, paths containing spaces, both runtime-option spellings, and all discovery outputs. Calling STREME by absolute path with --version is not sufficient.

For v0.2.8 onward, attach fp-tools-pbmc-chr22-demo-v1.zip and its SHA-256 sidecar before dispatching Release smoke. The Windows default case and macOS job also verify the tutorial archive and inputs, corrected command help, and the complete three-group single-cell workflow through the published desktop applications. Keep this real-data check separate from synthetic GUI fixtures.

The manual GitHub Actions Publish workflow uses the repository PYPI_API_TOKEN secret. Do not paste PyPI tokens into chat, shell history, or committed files. Rotate any token that was exposed outside a secret manager.

The manual GitHub Actions Publish workflow builds and tests every wheel, checks all artifacts, then uploads the complete set with the configured token. Do not publish when any platform wheel is absent.

5. Metadata And Docs

  • Confirm pyproject.toml version is correct.
  • Confirm project.urls point to https://github.com/oncologylab/fp-tools.
  • Confirm README renders correctly on GitHub.
  • Validate the MkDocs site locally with .venv/bin/mkdocs build --clean --strict, then push documentation changes to main. The GitHub Actions Docs workflow deploys GitHub Pages from main; do not use mkdocs gh-deploy or create a gh-pages branch for this repository.
  • When Playwright is installed, run .venv/bin/python scripts/audit_docs.py --site-dir site to check every documentation and demo page at desktop and mobile widths.
  • Confirm LICENSE, CITATION.cff, environment.yml, and Dockerfile are present and current.
  • Confirm pyproject.toml, src/fp_tools/__init__.py, CITATION.cff, release tag, and example version pins agree.

6. Data Hygiene

Do not commit:

  • downloaded public data under data/public/raw/ or data/public/processed/
  • benchmark result directories under benchmarks/results/
  • generated paper figures/tables except intentional manuscript previews and small examples
  • BAM/BAI fixtures beyond existing local-only test data

7. Paper/Benchmark Gate

Before using outputs in a manuscript:

  • freeze the exact public data manifest
  • save command logs and environment versions
  • validate benchmark manifests with python benchmarks/scripts/validate_manifests.py --manifest-dir benchmarks/manifests
  • save metrics tables used by each figure
  • label chromosome-4 benchmark results as pilot evidence unless whole-genome or chromosome-held-out validation has been completed
  • generate both vector and PNG figure outputs
  • write Data Availability and Code Availability notes