docs: Add boot failure detection documentation#1981
docs: Add boot failure detection documentation#1981cgwalters wants to merge 1 commit intobootc-dev:mainfrom
Conversation
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>
59876b3 to
8c894b8
Compare
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
| 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. |
There was a problem hiding this comment.
This sentence is a bit long and could be clearer. Consider splitting it or rephrasing the latter part for improved readability.
| 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. |
| 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 was a problem hiding this comment.
This sentence is quite long and contains multiple clauses. Splitting it into two or more sentences would significantly improve readability.
| 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: |
There was a problem hiding this comment.
The word "then" in "At the current time then" is redundant and can be removed for conciseness.
| 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. |
There was a problem hiding this comment.
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.
| 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. |
This came up in chat. Definitely the "enable tries integration for composefs" would make total sense.
Assisted-by: OpenCode (Sonnet 4.5)