Skip to content

docs: Add boot failure detection documentation#1981

Open
cgwalters wants to merge 1 commit intobootc-dev:mainfrom
cgwalters:boot-failure
Open

docs: Add boot failure detection documentation#1981
cgwalters wants to merge 1 commit intobootc-dev:mainfrom
cgwalters:boot-failure

Conversation

@cgwalters
Copy link
Collaborator

This came up in chat. Definitely the "enable tries integration for composefs" would make total sense.

Assisted-by: OpenCode (Sonnet 4.5)

@github-actions github-actions bot added the area/documentation Updates to the documentation label Feb 5, 2026
@bootc-bot bootc-bot bot requested a review from jeckersb February 5, 2026 01:56
This came up in chat. Definitely the "enable tries integration for
composefs" would make total sense.

Assisted-by: OpenCode (Sonnet 4.5)
Signed-off-by: Colin Walters <walters@verbum.org>
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

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

Code Review

The pull request successfully adds documentation for boot failure detection, covering both OSTree and composefs backends. The content is informative and well-structured. However, some sentences could be rephrased or split for improved clarity and readability, and a statement about future plans could be made more concise to avoid potential staleness in the documentation.


When `ostree-finalize-staged.service` fails during shutdown/reboot, this will create
a stamp file in `/boot`, and then on a subsequent reboot the `ostree-boot-complete.service`
service will detect it, and then itself exit with a failure mode.
Copy link
Contributor

Choose a reason for hiding this comment

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

medium

The phrasing "and then itself exit with a failure mode" is a bit awkward. Consider rephrasing for better clarity and flow.

Suggested change
service will detect it, and then itself exit with a failure mode.
service will detect it, and then exit with a failure mode.

Comment on lines +22 to +23
You can monitor the success of both services, though for `ostree-finalize-staged.service`
note that the failure occurred during the previous boot's shutdown.
Copy link
Contributor

Choose a reason for hiding this comment

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

medium

This sentence is a bit long and could be clearer. Consider splitting it or rephrasing the latter part for improved readability.

Suggested change
You can monitor the success of both services, though for `ostree-finalize-staged.service`
note that the failure occurred during the previous boot's shutdown.
You can monitor the success of both services. Note, however, that for `ostree-finalize-staged.service`, the failure occurred during the previous boot's shutdown.

Comment on lines +30 to +33
There is a `bootc-finalize-staged.service` which is similar to `ostree-finalize-staged.service`,
but there is not currently a similar `-boot-complete.service`. There is also a `bootc-root-setup.service`
that runs during initramfs to mount the composefs image and set up `/etc` and `/var` - but if this
service fails, the system will not boot at all (emergency mode or hang).
Copy link
Contributor

Choose a reason for hiding this comment

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

medium

This sentence is quite long and contains multiple clauses. Splitting it into two or more sentences would significantly improve readability.

Suggested change
There is a `bootc-finalize-staged.service` which is similar to `ostree-finalize-staged.service`,
but there is not currently a similar `-boot-complete.service`. There is also a `bootc-root-setup.service`
that runs during initramfs to mount the composefs image and set up `/etc` and `/var` - but if this
service fails, the system will not boot at all (emergency mode or hang).
There is a `bootc-finalize-staged.service` which is similar to `ostree-finalize-staged.service`, but there is not currently a similar `-boot-complete.service`. Additionally, a `bootc-root-setup.service` runs during initramfs to mount the composefs image and set up `/etc` and `/var`. If this service fails, the system will not boot at all (emergency mode or hang).

that runs during initramfs to mount the composefs image and set up `/etc` and `/var` - but if this
service fails, the system will not boot at all (emergency mode or hang).

At the current time then, it is recommended to check the journal for failures from the previous boot:
Copy link
Contributor

Choose a reason for hiding this comment

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

medium

The word "then" in "At the current time then" is redundant and can be removed for conciseness.

Suggested change
At the current time then, it is recommended to check the journal for failures from the previous boot:
At the current time, it is recommended to check the journal for failures from the previous boot:

As of a recent OSTree with [this commit](https://github.com/ostreedev/ostree/commit/08487091256b93493f8d692e37ab3d892c758da1)
it is possible to configure the boot loader entry counting.

At the current time, the composefs backend does not configure boot entry counting, this is likely to be added in the future.
Copy link
Contributor

Choose a reason for hiding this comment

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

medium

Statements about future plans like "this is likely to be added in the future" can quickly become outdated in documentation. It's generally better to state the current facts or phrase it more cautiously, e.g., "This feature is planned for future releases" or simply omit it if it's not critical for understanding the current state.

Suggested change
At the current time, the composefs backend does not configure boot entry counting, this is likely to be added in the future.
At the current time, the composefs backend does not configure boot entry counting.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/documentation Updates to the documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant