Add bib deprecation notice by jlsherrill · Pull Request #197 · osbuild/osbuild.github.io

jlsherrill · 2026-03-20T19:30:56Z

This is up for discussion and review, do not consider any part of this final at this time.

ochosi

<3

achilleas-k · 2026-03-20T19:53:02Z

The transparent image doesn't work well with dark mode. Black text disappears.

achilleas-k · 2026-03-20T19:54:59Z

But the words are great. Nicely explains everything.

bcl · 2026-03-20T20:06:03Z

docs/bootc/deprecation-notice.md

+### RHEL 9/10 (and current container)
+
+- **Backward compatibility is guaranteed for the full life of RHEL 10.** Existing automation, documentation, and pipelines that run the container with a **bootc-image-builder** entry point remain supported.
+- **Starting in RHEL 9.7/10.2** bootc-image-builder will start only shipping new major versions with each RHEL Y release.  Upstream releases will no longer be backports to the RHEL 10.Y image. 


backported not backports

bcl · 2026-03-20T20:13:09Z

Looks pretty good to me, but I notice inconsistent use of image-builder, image-builder-cli and image-builder CLI in various places. I'm not even sure what to call it :) I don't think we can just call it image-builder without causing confusion with the UI, right? image-builder-cli seems like the least confusing thing to me, except when explicitly showing what command line to execute -- eg. image-builder list

supakeen · 2026-03-20T20:56:22Z

Looks pretty good to me, but I notice inconsistent use of image-builder, image-builder-cli and image-builder CLI in various places. I'm not even sure what to call it :) I don't think we can just call it image-builder without causing confusion with the UI, right? image-builder-cli seems like the least confusing thing to me, except when explicitly showing what command line to execute -- eg. image-builder list

The idea (at least for me is):

Package: image-builder (already the case).
Executable: image-builder (already the case).
Repository: github.com/osbuild/image-builder (we've wanted to rename it for ages but I don't know what we're currently blocked on).
Container: ghcr.io/osbuild/image-builder.

When referring to it in a sentence you can use "the image builder cli" or such 🙂.

supakeen

Thanks for working on this. I have some (mostly naming) comments.

Will we make an image-builder container available downstream with RHEL 9.9/10.3 as well? If that's the case then I think a lot here can be simplified to "start using the image-builder container or package" but I've mentioned this in comments.

supakeen · 2026-03-20T20:58:46Z

docs/bootc/deprecation-notice.md

+
+## Why we're deprecating bootc-image-builder
+
+We are unifying the tooling so that one CLI and one container can build images from both **blueprints** (package mode) and **bootable containers** (image mode). The unified [image-builder](https://www.osbuild.org/docs/developer-guide/projects/image-builder/) project already supports building from bootc container inputs via `--bootc-ref` and related options, with functional equivalence to what bootc-image-builder provides. Maintaining two separate codebases and containers is no longer necessary; consolidating reduces maintenance and gives users a single entry point for all image-building workflows.


I would write this as 'so that one CLI can build images from packages, and convert bootable containers' (we're not really building the bootable container images, at least the terminology gets fuzzy here).

You can also directly link to the usage section for bootc in the image-builder docs: https://osbuild.org/docs/developer-guide/projects/image-builder/usage/#bootc

supakeen · 2026-03-20T21:00:23Z

docs/bootc/deprecation-notice.md

+
+### RHEL 9/10 (and current container)
+
+- **Backward compatibility is guaranteed for the full life of RHEL 10.** Existing automation, documentation, and pipelines that run the container with a **bootc-image-builder** entry point remain supported.


I would say "that run the bootc-image-builder container or executable remain supported".

Us switching the bootc-image-builder container to build from the image-builder-cli (with a symlink and stuff) is really an implementation detail that should be unnoticeable.

it is an implementation detail, but given that we are archiving the bib git repo, i think it makes sense to explain. Happen to remove if there's consensus to though.

supakeen · 2026-03-20T21:02:04Z

docs/bootc/deprecation-notice.md

+
+- **Backward compatibility is guaranteed for the full life of RHEL 10.** Existing automation, documentation, and pipelines that run the container with a **bootc-image-builder** entry point remain supported.
+- **Starting in RHEL 9.7/10.2** bootc-image-builder will start only shipping new major versions with each RHEL Y release.  Upstream releases will no longer be backports to the RHEL 10.Y image. 
+- **Starting in RHEL 9.8/10.3**, the RHEL image-building container will be built on **image-builder-cli** (the unified implementation). It will **not** ship the original standalone bootc-image-builder binary. Instead, the container exposes a **bootc-image-builder entry point** that wraps image-builder-cli so that existing `podman run … bootc-image-builder` style invocations keep working without changing flags or workflows.  A new container **image-builder** will be shipped that contains the same binary as bootc-image-builder, but without the compatibility entry point.  Both the **bootc-image-builder** and **image-builder** containers will ship with the same version of image-builder-cli that is available as an rpm in respective RHEL release. 


This is the same implementation detail that doesn't need to be mentioned. It's transparent to users.

If we do keep it then please refer specifically to the RHEL bootc-image-builder container and say it's build on image-builder.

supakeen · 2026-03-20T21:02:56Z

docs/bootc/deprecation-notice.md

+
+### RHEL 11
+
+- **Only the image-builder container and CLI will be shipped.** The **bootc-image-builder** compatibility entry point will no longer be provided.


Replace CLI with package here and I'd say "the bootc-image-builder container and executable will no longer be available in RHEL 11".

supakeen · 2026-03-20T21:03:16Z

docs/bootc/deprecation-notice.md

+### RHEL 11
+
+- **Only the image-builder container and CLI will be shipped.** The **bootc-image-builder** compatibility entry point will no longer be provided.
+- Consumers must complete migration to the image-builder CLI before relying on RHEL 11 or building RHEL 11.


"to the image-builder package or container before".

supakeen · 2026-03-20T21:04:10Z

docs/bootc/deprecation-notice.md

+
+## What you should do
+
+1. **Prefer the image-builder CLI for new work.** Use the [image-builder](https://www.osbuild.org/docs/developer-guide/projects/image-builder/) documentation and invoke **image-builder** as the container entry point (or install the CLI on the host). From RHEL 10.3 onward, the RHEL container is image-builder-cli-based; the bootc-image-builder entry point exists only for backward compatibility.


I would say "prefer the image-builder package or container" and skip the entrypoint stuff.

jlsherrill requested a review from a team as a code owner March 20, 2026 19:30

jlsherrill requested review from lucasgarfield and ochosi and removed request for a team March 20, 2026 19:30

ochosi previously approved these changes Mar 20, 2026

View reviewed changes

Add bib deprecation notice

1d0c87d

jlsherrill dismissed ochosi’s stale review via 1d0c87d March 20, 2026 19:37

jlsherrill force-pushed the depre branch from 45a95cf to 1d0c87d Compare March 20, 2026 19:37

bcl reviewed Mar 20, 2026

View reviewed changes

supakeen self-requested a review March 20, 2026 20:56

supakeen reviewed Mar 20, 2026

View reviewed changes


		## Why we're deprecating bootc-image-builder

		We are unifying the tooling so that one CLI and one container can build images from both blueprints (package mode) and bootable containers (image mode). The unified [image-builder](https://www.osbuild.org/docs/developer-guide/projects/image-builder/) project already supports building from bootc container inputs via `--bootc-ref` and related options, with functional equivalence to what bootc-image-builder provides. Maintaining two separate codebases and containers is no longer necessary; consolidating reduces maintenance and gives users a single entry point for all image-building workflows.


		### RHEL 9/10 (and current container)

		- Backward compatibility is guaranteed for the full life of RHEL 10. Existing automation, documentation, and pipelines that run the container with a bootc-image-builder entry point remain supported.


		### RHEL 11

		- Only the image-builder container and CLI will be shipped. The bootc-image-builder compatibility entry point will no longer be provided.


		## What you should do

		1. Prefer the image-builder CLI for new work. Use the [image-builder](https://www.osbuild.org/docs/developer-guide/projects/image-builder/) documentation and invoke image-builder as the container entry point (or install the CLI on the host). From RHEL 10.3 onward, the RHEL container is image-builder-cli-based; the bootc-image-builder entry point exists only for backward compatibility.

Conversation

jlsherrill commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ochosi left a comment

Choose a reason for hiding this comment

Uh oh!

achilleas-k commented Mar 20, 2026

Uh oh!

achilleas-k commented Mar 20, 2026

Uh oh!

bcl Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

bcl commented Mar 20, 2026

Uh oh!

supakeen commented Mar 20, 2026

Uh oh!

supakeen left a comment

Choose a reason for hiding this comment

Uh oh!

supakeen Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

supakeen Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

jlsherrill Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

supakeen Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

supakeen Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

supakeen Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

supakeen Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jlsherrill commented Mar 20, 2026 •

edited

Loading

supakeen Mar 20, 2026 •

edited

Loading