🌱 (infra/demos): Remove asciicinema demos

[vitorfloriano]

This PR removes the asciicinema demos and generation scripts from the repo and updates the README.

Motivation

While the visual recording is neat, it introduces significant friction:

• Tooling dependency & complexity: Generating this artifact requires specific external tools (asciinema, scripts, etc.). This adds unnecessary complexity to the contribution workflow. Contributors usually spend significant time working on the updates.

• Maintenance burden: Because of the tooling friction, the GIF is rarely updated. As CLI flags and outputs evolve, the recording drifts from reality, becoming misleading technical debt.

• Accessibility & usability: The GIF is invisible to screen readers, unsearchable, and prevents users from copy-pasting commands. Also, users can't pause or change the playback speed to follow along, making it not so useful for educational purposes.

Proposed Solution

Remove the demo gif and focus on providing commands in code blocks within the written documentation. This removes the dependency on generation tools and ensures the docs are accessible and easy to patch in any future PR.

As a bonus, we get to remove 1MB of binaries.

Closes #4552
Closes #5068

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: vitorfloriano
Once this PR has been reviewed and has the lgtm label, please assign varshaprasad96 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[camilamacedo86]

Hi @vitorfloriano 👋

I understand the concerns, but I don’t think removing asciinema is the right approach.

Asciinema is very valuable for CLI demos. Instead of removing it, we could configure it like in operator-controller:
https://github.com/openshift/operator-framework-operator-controller/blob/main/Makefile#L556-L565

There, demos are scripted and recorded automatically, similar to make generate. Contributors only update the script, and the demo is regenerated.

Regarding the points raised:

Tooling dependency & complexity
If set up properly, asciinema is easy to use.
Contributors only write scripts; recording happens automatically.
This tooling does not affect end users, since asciinema is not a Kubebuilder runtime dependency.

Maintenance burden
With scripted demos, recordings stay in sync with CLI changes.
Maintenance becomes part of the normal workflow, not extra work.

Accessibility & usability
Asciinema recordings can be paused and replayed.
They are very helpful to understand CLI flows and complement the written docs.

Overall, I think improving and automating asciinema demos gives strong value to users, instead of removing them entirely.

Thanks 🙏

[vitorfloriano]

Hi @camilamacedo86

I still think maintaining the scripts and adding another step to the doc update workflow for a single animation in README is not worth the effort.

Also, while Asciicinema does have a nice webplayer, it is not possible to embed that player in markdown files on GitHub (see: asciinema/discussions#283). Users have to work around that limitation by exporting the animation to .svg or .gif format, which does not allow the users to pause, copy & paste, go back or forward, alter playback speed or anything. The demo in README is in .svg. If you click on it, it will open the file in another tab. You can't control its playback (unless your're using Safari).

The Web Content Accessibility Guidelines (WCAG 2.0) recommend that users should be able to play, pause, stop and hide animated content. The non-stop .svg animation in README does not provide that.

Although not directly related, some style guides have directives against using gifs or animated recording in docs:

"For animations and videos, don't use animated GIF. Instead, use a more resource-efficient format (such as MP4)." - Google Style Guide
"Avoid animated images (such as animated GIFs). They can be distracting and annoying for users." - GitLab Style Guide

I'm not saying that the Asciicinema demo are not useful, but the way we are displaying it in the README does not make it very accessible and educational. Keeping that demo updated seems like maintenance burden.

We could still add Asciicinema to the Kubebuilder book, because we would be able to use the webplayer there. It is currently not used anywhere in there, though.

[camilamacedo86]

Hi @vitorfloriano

But is easier just update the script and review a PR with changes in the script then review GIFs or anything else and we need the demos. The demos are important to show how things work for end users. We should have more demos.

[vitorfloriano]

@camilamacedo86

I agree that more demos are needed. I just don't think that THAT specific demo in README is helpful. We had to export it as an .svg animation, not an Asciicinema .cast recording. You can't control its playback, you can't copy its text, the font size is small. It's not accessible.

We could still add demos as Asciicinema .cast recordings to the Kubebuilder book, but we would have to decide where to put them because currently there are no asciicinema demos in there.

[vitorfloriano]

@camilamacedo86 Complementing the previous comment:

If you look at the README in the scripts dir, you'll notice that there is a workaround to convert the asciicinema original recording to .svg using yet another tool, svg-term:

https://github.com/kubernetes-sigs/kubebuilder/blob/master/scripts/demo/README.md?plain=1#L29-L32

They had to convert the asciicinema .cat output to .svg because GitHub does not render the webplayer.

[camilamacedo86]

Hi @vitorfloriano 👋

Thanks for the explanation — I understand your concerns and I agree that the current SVG demo in the README is not ideal.

That said, I still believe we should have demos. CLI projects like Kubebuilder really benefit from showing real flows, not only text.

I also agree that reviewing GIFs or SVGs is a bad workflow. That’s exactly why demos should be:

• scripted
• generated automatically
• reviewed as script changes, not as visual artifacts

Because of this, I don’t see a better option than asciinema.

The GitHub README limitation is real (no web player), but there is a good solution already used in operator-controller:
https://github.com/operator-framework/operator-controller

There, the README only shows a preview image that links to asciinema, and the real, accessible player runs on asciinema.org. Contributors only update scripts, and all demos can be regenerated via make.

So instead of removing everything, I think we should:

• keep asciinema as the source of truth
• remove animated SVG/GIF playback from the README
• link to asciinema recordings like operator-controller
• provide a generic make target to regenerate all demos

This keeps demos useful, accessible, and easy to maintain.

Thanks 🙏

[vitorfloriano]

Hi @camilamacedo86

A static image that links to the demo on asciicinema.org seems to be a better option.

I'm just thinking if it's possible to automate that, since uploading the demo to asciicinema.org would require authentication.

Besides that, every asciicinema upload has a unique URL so we would need to parse the new address to change the link in the static image so it would point to the updated demo.

Another concern I have is about what account will be used to store the demos. For example, the operator-controller demo you mentioned is stored in a contributor account (jordank). It would be nicer if kubebuilder had its own "official" account and the script would somehow upload to it.

[camilamacedo86]

HI @vitorfloriano

I'm just thinking if it's possible to automate that, since uploading the demo to asciicinema.org would require authentication.

Yes, it is possible since it is done in operator-controller
See; https://github.com/operator-framework/operator-controller/blob/main/Makefile#L572-L579

[vitorfloriano]

Yes, it is possible since it is done in operator-controller
See; https://github.com/operator-framework/operator-controller/blob/main/Makefile#L572-L579

@camilamacedo86 I was taking a look at the generation script and I couldn't see how it handles the authentication on uploads. I understand that the user must be logged in to be able to upload the demos to asciicinema.org.

The only way I can think of making this work is to create an account for kubebuilder and store the authentication info in a repo secret, then use this secret in GitHub Actions.