Skip to content

Terminal interface to find, download, and stream movies, TV shows, and live TV using local media players.

docs: add release readiness checklist

Samir Hossains56cf42bae9af
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9e84cb2..312a814 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -66,6 +66,9 @@ commit is rejected if either fails. There is no need to run them manually.
If the hook rejects a commit, run `cargo fmt` to auto-fix the formatting, then stage and
commit again.
+For release readiness, static checks are not enough on their own. Before declaring a
+release production-ready, work through [`docs/release-checklist.md`](docs/release-checklist.md).
+
**Guidelines:**
- Follow idiomatic Rust and standard `rustfmt` defaults. Don't hand-format.
- Keep the async, message-passing architecture intact.
diff --git a/README.md b/README.md
index 114366b..46afda7 100644
--- a/README.md
+++ b/README.md
@@ -393,7 +393,9 @@ cargo package --locked
GitHub Actions also verifies cross-platform builds on Linux, macOS, and Windows,
plus an Android/Termux cross-build lane.
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidance.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidance and
+[`docs/release-checklist.md`](docs/release-checklist.md) for the runtime checks still
+required before calling a release production-ready.
## License
diff --git a/docs/README.md b/docs/README.md
index e089238..865d00d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,6 +18,7 @@ anchors that stay accurate as the code evolves.
| [config.md](config.md) | `config.json` fields and `MOVIEBOX_*` environment variables | current |
| [downloads.md](downloads.md) | Download engine: resume, ranges, segments, retry, cancel | current |
| [cross-platform.md](cross-platform.md) | OS support, terminal protocols, Termux, focus handling | current |
+| [release-checklist.md](release-checklist.md) | Static gates plus required real-environment release verification | current |
| [debugging.md](debugging.md) | Reproducing issues and what to include in GitHub reports | current |
| [known-issues.md](known-issues.md) | Known limitations and how they are tracked | current |
diff --git a/docs/release-checklist.md b/docs/release-checklist.md
new file mode 100644
index 0000000..5c4f1e9
--- /dev/null
+++ b/docs/release-checklist.md
@@ -0,0 +1,105 @@
+# Release Checklist
+
+Use this before calling a new build production-ready. Static gates are necessary but not
+sufficient for this project because player launch, terminal rendering, and Termux
+chooser behavior depend on the real runtime environment.
+
+## 1. Static gates
+
+Run the repository checks first:
+
+```bash
+cargo fmt --check
+cargo clippy --all-targets --locked -- -D warnings
+cargo check --locked
+cargo test --locked
+cargo audit
+cargo package --locked
+```
+
+Confirm the main GitHub Actions workflows are green:
+
+- `CI`
+- `Release`
+- `Publish to Crates.io` when applicable
+- `Update Homebrew Formula` when applicable
+
+## 2. Desktop playback checks
+
+Verify at least one real playback launch on each supported desktop OS:
+
+- macOS: IINA and/or mpv/VLC
+- Linux: mpv and/or VLC
+- Windows: mpv and/or VLC
+
+For each checked platform, confirm:
+
+- the player launches from MovieBox-Tui
+- the window size is reasonable
+- playback works for a source with no extra headers
+- playback works for a source carrying `Referer` / `User-Agent`
+- subtitles still attach for mpv / VLC / IINA
+
+## 3. Terminal rendering checks
+
+Verify poster rendering on the terminal families the docs claim to support:
+
+- Kitty protocol terminal
+- Sixel-capable terminal
+- basic half-block fallback terminal
+
+Confirm:
+
+- posters appear on search/details screens
+- resize redraw still works
+- focus loss/gain redraw does not corrupt the screen after returning from playback
+
+## 4. TV mode checks
+
+Verify TV mode with both supported playlist source types:
+
+- remote `http(s)` M3U
+- local file M3U
+
+Confirm:
+
+- playlist import succeeds
+- broken playlists report an error without breaking the app
+- dedupe by stream URL still behaves correctly
+- `/config` and `/list` work in TV mode
+- channel playback launches the player
+
+## 5. Termux / Android checks
+
+Verify on a real Termux device before calling the release production-ready:
+
+- app starts normally
+- `Play` opens the Android chooser through `termux-open` or `/system/bin/am`
+- chosen player starts playback
+- downloads still go where the docs describe
+
+This remains mandatory because chooser behavior is device/environment dependent.
+
+## 6. Release artifact checks
+
+Verify the published release contains:
+
+- expected archives for macOS, Linux x64, Linux arm64, Windows x64, Windows arm64,
+ and Termux arm64
+- `SHA256SUMS`
+- working install scripts / formula references
+
+Spot-check:
+
+- `install.sh`
+- `install.ps1`
+- Homebrew formula install path
+
+## Exit criteria
+
+Only call the release production-ready when:
+
+- all static gates pass
+- the relevant GitHub Actions workflows pass
+- the runtime checks above were performed on real target environments
+- no open blocker remains in `docs/known-issues.md` for the release target