Skip to content

docs: add VHS demo screencast pipeline#109

Merged
rominf merged 6 commits into
mainfrom
docs/demo-screencasts
Jul 17, 2026
Merged

docs: add VHS demo screencast pipeline#109
rominf merged 6 commits into
mainfrom
docs/demo-screencasts

Conversation

@rominf

@rominf rominf commented Jul 13, 2026

Copy link
Copy Markdown
Collaborator

Summary

Automates terminal demo GIFs for the README so they are generated in CI and never committed to source branches.

  • Adds two composite VHS demos: a CLI first-use journey and a full-screen Console tour.
  • Adds a demo-gifs workflow that builds the binaries, renders both tapes, and publishes the GIFs to an orphan media branch. The README embeds them by absolute raw URL.
  • Reuses the e2e mock OpenAI server through a standalone rocm-demo-env helper for the server-backed CLI steps. It creates an isolated service record and exposes the environment needed by rocm, without a GPU or real model.
  • Shares the service-record writer between the cucumber test world and demo helper so their schemas cannot drift.
  • Makes the mock chat reply configurable through ROCM_MOCK_CHAT_REPLY so the screencast uses natural demo text while tests retain their existing default.

Why

The README has no visual overview of the CLI. Deterministic, CI-rendered demos give users an at-a-glance view of the CLI and Console without maintaining hand-recorded GIFs or adding binary artifacts to main.

Triggers

The workflow runs on workflow_dispatch and published releases, never on pull requests. Rendering is comparatively slow and would otherwise churn the generated-media branch. Release tags also provide image-cache busting for GitHub's proxy.

Verification

  • Full pre-push gates pass: formatting, clippy, workspace tests, YAML validation, license checks, and commit signature/sign-off verification.
  • cargo test -p xtask passes, including demo selection and readiness parsing.
  • rocm-demo-env builds successfully and the e2e test target compiles with the shared service-record helper.
  • The demo-gifs workflow has rendered and published both composite demos successfully.

Dependency / scope

The e2e harness dependency from #69 has merged. This PR does not change product runtime paths; it adds documentation tooling, deterministic mock-backed demos, and generated-media publication.

Risk

Low. Existing test behavior is preserved by default, and generated GIFs remain isolated from source history.

@rominf
rominf force-pushed the docs/demo-screencasts branch 3 times, most recently from 45b5eda to b7a01d8 Compare July 13, 2026 18:50
@fredespi
fredespi force-pushed the test/add-e2e-robot-framework branch from 6d309d7 to 204c4e8 Compare July 15, 2026 12:59
Base automatically changed from test/add-e2e-robot-framework to main July 15, 2026 15:49
@rominf
rominf force-pushed the docs/demo-screencasts branch from b7a01d8 to 804705b Compare July 15, 2026 16:18
rominf added 2 commits July 17, 2026 09:21
Generate terminal demo GIFs for the README from VHS tapes, rendered in
CI and published to an orphan `media` branch so no binaries land in the
source history. The README embeds them by absolute raw URL.

Tapes are pure command sequences; all setup (build dir on PATH, isolated
config, the mock server) is done by docs/tapes/render.sh BEFORE vhs runs.
This is deliberate: VHS types on a fixed clock and never waits for a
command to return, so setup done inside a tape races the typing.

Server-backed demos (chat, services) reuse the e2e harness's mock OpenAI
server via a new standalone `rocm-demo-env` binary: it starts the mock,
plants a managed-service record into an isolated config, and prints the
env that points `rocm` at it — no GPU or real model needed. The record
schema is shared with the cucumber World via `write_service_record` so
the two can't drift. The mock ignores SIGINT/SIGHUP (VHS/ttyd emit some
during terminal setup) and stops on SIGTERM, so it survives until the
tape runs. Its chat reply is overridable via ROCM_MOCK_CHAT_REPLY.

Rendering runs on workflow_dispatch and on release (never on PRs, where
it would be slow and churn the branch); the release tag doubles as an
image-cache buster.

Stacked on #69 (the e2e harness this reuses); keep as draft until it lands.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
@rominf
rominf force-pushed the docs/demo-screencasts branch from 760e977 to 5b889ae Compare July 17, 2026 09:31
Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
Comment thread xtask/src/demos.rs Dismissed
Comment thread xtask/src/demos.rs Dismissed
rominf added 2 commits July 17, 2026 12:20
Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
@rominf
rominf marked this pull request as ready for review July 17, 2026 13:06
@EugeneKSiloAi

Copy link
Copy Markdown
Collaborator

Blocking / must-fix before merge to main

  1. Unpinned actions/checkout@v6 violates the repo's own action-pinning rule.
    - uses: actions/checkout@v6
    AGENTS.md §6 requires pinning actions to a full commit SHA with a trailing # vX.Y.Z comment, never a moving tag. The other two actions in this same file are correctly pinned (setup-rust-toolchain@166cdc… # v1.17.0, peaceiris@84c30a… # v4.1.0), and the dominant convention across ci.yml/release.yml/nightly.yml is actions/checkout@df4cb1c # v6.0.3. Match it here for consistency and supply-chain safety. (There are pre-existing @v6 stragglers elsewhere, but a new file shouldn't add another.)

  2. The temporary feature-branch trigger must be removed before merging.
    branches: [docs/demo-screencasts]
    The inline comment already acknowledges this is scaffolding ("The feature-branch push trigger is temporary"). It's dead weight on main and, combined with the commit eb4edea ci: trigger demo render on feature branch, is exactly the kind of dev-loop churn the OSS workflow (§11: "one logical change") says to clean up. Drop the push: trigger (and squash the scaffolding commits) as part of the pre-merge rebase you noted.

  3. Misleading comment in the "Stage rendered media" step.

demo-gifs.yml
Lines 55-61
      # Publish from an unignored staging directory. `docs/media/*.gif` is
      # intentionally git-ignored on source branches, and the Pages action honors
      # that ignore file while preparing assets.

peaceiris/actions-gh-pages publishes publish_dir (./rendered-media) with force_orphan; it does not consult docs/media/.gitignore. The staging copy is needed precisely because docs/media is git-ignored — the "Pages action honors that ignore file" clause is inaccurate and could mislead a future maintainer. Reword to just explain the staging copy.

  1. Fictitious model id shown in a user-facing demo. Qwen/Qwen3.5-0.6B (in cli.tape, rocm-demo-env.rs, demos.rs) isn't a real model — Qwen3.5 has no 0.6B variant, and it's not in model_catalog.json (which has Qwen/Qwen3.5-4B). It works because the mock advertises whatever it's told, but a reviewer/user watching the GIF may notice. Consider using a real catalog id (e.g. Qwen/Qwen3.5-4B) so the screencast doesn't teach a non-existent model. Purely cosmetic, but it's the visible artifact this PR exists to produce.

Nits (optional)

  • PR description drift. The description says "four demos (version, engines list, services list, one-shot chat)" and per-command tapes; the implementation consolidated to two composite tapes (cli, console). Worth syncing the description so reviewers aren't hunting for four tape files.
  • rocm-demo-env standalone reply. When run directly (as demos.md/demo-env.sh suggests for manual testing), ROCM_MOCK_CHAT_REPLY is unset, so rocm chat returns the test stub rather than the natural reply — only xtask demos sets it. Fine, but the manual-run docs could mention exporting it if you want the realistic reply.
  • README lands with 404 image links until the workflow runs once. Acknowledged inline. Since the release trigger is the first realistic fire, consider a one-time manual workflow_dispatch right after merge so main's README isn't broken in the interim.


jobs:
render:
runs-on: ubuntu-latest

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would it make sense to pin to a version in case version update causes breakage in the future.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes—pinned actions/checkout to the repository-standard full SHA for v6.0.3 in 3523dc3. I also ran the full pre-push gates successfully. Leaving this open for your re-review.

@clydehoang1 clydehoang1 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can pre-approve assuming the security and quality checks are addressed.

Signed-off-by: Roman Inflianskas <Roman.Inflianskas@amd.com>
@rominf

rominf commented Jul 17, 2026

Copy link
Copy Markdown
Collaborator Author

Addressed the review in 3523dc3:

  • pinned actions/checkout to the full v6.0.3 SHA;
  • removed the temporary feature-branch trigger;
  • corrected the generated-media staging explanation;
  • replaced the fictional model identifier with catalog entry Qwen/Qwen3.5-4B everywhere;
  • documented ROCM_MOCK_CHAT_REPLY for direct helper runs; and
  • updated the PR description for the two composite CLI/Console demos and the now-merged test: add BDD E2E tests with cucumber-rs #69 dependency.

I left the existing commits intact because this repository squash-merges PRs, so the temporary scaffolding commits will not enter main; rewriting after review would only add force-push churn.

The full pre-push suite passes after a clean rebuild: YAML validation, formatting, clippy, workspace tests, license checks, and signature/sign-off verification. CodeQL alerts 716 and 717 were independently security-reviewed and dismissed as false positives; their threads remain open for re-review.

After merge, the workflow should be dispatched once from main so the README media remains immediately available before the next release trigger.

@rominf
rominf added this pull request to the merge queue Jul 17, 2026
Merged via the queue into main with commit 76c1c50 Jul 17, 2026
33 of 35 checks passed
@rominf
rominf deleted the docs/demo-screencasts branch July 17, 2026 18:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants