docs: Update composefs finalization docs#2168
docs: Update composefs finalization docs#2168cgwalters wants to merge 1 commit intobootc-dev:mainfrom
Conversation
This came up during review of PR bootc-dev#2161, where the PR description incorrectly claimed composefs status detection conflates booted and staged deployments. The composefs-finalize-staged man page was mostly a stub, and what we really want to document is the service, not the command. Make the command hidden and move the man page to be about the service. Update the internals docs for more about this too. Assisted-by: OpenCode (Claude Opus 4) Signed-off-by: Colin Walters <walters@verbum.org>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request documents the composefs backend's deployment identification, staging, and finalization processes. It hides the internal composefs-finalize-staged command from the CLI and adds a new man page for the bootc-finalize-staged.service. Feedback includes standardizing the man page's NAME section for better indexing and correcting the technical description of the renameat2 system call flag.
| # NAME | ||
|
|
||
| bootc-finalize-staged.service |
There was a problem hiding this comment.
The NAME section in a man page should follow the standard format: name - summary description. This allows tools like apropos to correctly index the service and provides a quick overview for users.
| # NAME | |
| bootc-finalize-staged.service | |
| # NAME | |
| bootc-finalize-staged.service - Finalize a staged composefs deployment at shutdown |
| have local modifications), and the new deployment's `/etc`. | ||
|
|
||
| 4. Atomically swaps the boot loader entries: `loader/entries.staged` is | ||
| exchanged with `loader/entries` via a single `RENAME_EXCHANGE` syscall, |
There was a problem hiding this comment.
RENAME_EXCHANGE is a flag for the renameat2 system call, rather than a system call itself. Referring to the specific syscall is more technically accurate and consistent with the description in the internals documentation.
| exchanged with `loader/entries` via a single `RENAME_EXCHANGE` syscall, | |
| exchanged with loader/entries via a single renameat2(RENAME_EXCHANGE) syscall, |
2 participants
This came up during review of PR #2161, where the PR description incorrectly claimed composefs status detection conflates booted and staged deployments.
The composefs-finalize-staged man page was mostly a stub, and what we really want to document is the service, not the command. Make the command hidden and move the man page to be about the service.
Update the internals docs for more about this too.
Assisted-by: OpenCode (Claude Opus 4)