docs: Add architecture documentation to internals page #1948
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
area/install
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request significantly enhances the internal documentation, providing a comprehensive overview of the project's architecture, module organization, and storage backends. The updates to crates/lib/src/lib.rs and docs/src/internals.md are particularly valuable for developers working on the project. Additionally, several minor stylistic improvements have been made across various Rust files to ensure better Markdown rendering of URLs and code snippets in comments.
cgwalters
force-pushed
the
more-internals-docs
branch
from
ae84615 to
f63cce9
Compare
cgwalters
force-pushed
the
more-internals-docs
branch
from
f63cce9 to
f037998
Compare
Wrap bare URLs in angle brackets to make them proper hyperlinks, escape angle brackets in doc comments that look like HTML tags, and fix broken intra-doc links. Assisted-by: OpenCode (Sonnet 4) Signed-off-by: Colin Walters <walters@verbum.org>
Extend our internals docs to have more information. Assisted-by: OpenCode (Sonnet 4) Signed-off-by: Colin Walters <walters@verbum.org>
Add comprehensive documentation for the installation process, with particular
focus on the Discoverable Partitions Specification (DPS) and first-boot
provisioning.
Main documentation (bootc-install.md):
- Add DPS section explaining partition type GUIDs and auto-discovery
- Add table showing when DPS vs explicit root= kargs are used
- Add provisioning and first boot section covering cloud-init,
Ignition, SSH key injection, and custom provisioning
- Document the .bootc-aleph.json provenance file
- Fix typos ('boot install' -> 'bootc install', 'pased' -> 'passed')
Man page (bootc-install-to-disk.8.md):
- Document partition layout conceptually (avoiding specific sizes/GUIDs
that may change between versions)
- Explain root filesystem discovery with systemd-gpt-auto-generator
Rustdoc for install.rs:
- Add comprehensive module documentation
- Document all installation modes (to-disk, to-filesystem, to-existing-root, reset)
- Explain OSTree vs Composefs storage backends
- Document key types (State, RootSetup, SourceInfo, SELinuxFinalState)
- List configuration paths and submodules
Rustdoc for discoverable_partition_specification.rs:
- Explain how bootc uses DPS for partition creation
- Document automatic root discovery mechanism
- Describe composefs and sealed boot integration
Assisted-by: OpenCode (Claude Sonnet 4)
Signed-off-by: Colin Walters <walters@verbum.org>
Document how container images are stored as ostree commits, including: container/mod.rs: - On-disk storage structure (ref namespace, layer storage, merge commit) - Import flow from manifest fetch through merge commit creation - Tar stream format and connection to deployments - Signature verification options - Key types and submodules container/store.rs: - Reference namespace constants and their purposes - Three-step import process (create, prepare, execute) - Layer types (commit, component, derived) and their handling - Merge commit metadata keys - Layer caching and deduplication strategy - Garbage collection behavior - Example usage lib.rs: - Add key modules section highlighting container, tar, sysroot, chunking This complements the recent installation documentation by explaining how container images are actually stored on disk in the ostree repository. Assisted-by: OpenCode (Claude Sonnet 4) Signed-off-by: Colin Walters <walters@verbum.org>
cgwalters
force-pushed
the
more-internals-docs
branch
from
f037998 to
aed41d2
Compare
jeckersb
approved these changes
Jan 28, 2026
Collaborator
jeckersb
left a comment
jeckersb
left a comment
There was a problem hiding this comment.
LGTM, I rekicked CI, we'll see how that shakes out
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Extend our internals docs to have more information.