mirror of
https://github.com/edera-dev/sprout.git
synced 2026-11-04 19:02:20 +00:00
83 lines
4.3 KiB
Markdown
83 lines
4.3 KiB
Markdown
|
---
|
||
|
|
name: update-config-docs
|
||
|
|
description: Bring CONFIG.md back in line with the code. Use after changing anything in crates/config, the command line options, loader.conf handling, strict mode, or autoconfiguration, or when asked to check that CONFIG.md is accurate.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Update CONFIG.md
|
||
|
|
|
||
|
|
`CONFIG.md` is the reference for `sprout.toml`, the command line options, BLS support and strict mode.
|
||
|
|
The README only links to it, so a setting that is missing from CONFIG.md is undocumented.
|
||
|
|
|
||
|
|
## 1. Find what changed
|
||
|
|
|
||
|
|
Start from the diff, or from the whole config surface if there is none:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git diff main -- crates/config crates/boot/src/options.rs crates/boot/src/config crates/boot/src/autoconfigure crates/bls
|
||
|
|
```
|
||
|
|
|
||
|
|
The sources of truth, and the section of CONFIG.md each one feeds:
|
||
|
|
|
||
|
|
| Source | Section |
|
||
|
|
|-----------------------------------------------------------|-------------------------------------------|
|
||
|
|
| `crates/config/src/lib.rs` | file at a glance, `options` |
|
||
|
|
| `crates/config/src/drivers.rs` | `drivers` |
|
||
|
|
| `crates/config/src/extractors*` | `extractors` |
|
||
|
|
| `crates/config/src/actions*` | `actions` |
|
||
|
|
| `crates/config/src/entries.rs` | `entries` |
|
||
|
|
| `crates/config/src/generators*` | `generators`, `variants`, `exclude` |
|
||
|
|
| `crates/config/src/phases.rs` | `phases` |
|
||
|
|
| `crates/boot/src/options.rs` | command line options |
|
||
|
|
| `crates/boot/src/main.rs` | boot order, defaults, timeout and default entry order, strict mode |
|
||
|
|
| `crates/boot/src/autoconfigure*` | autoconfiguration |
|
||
|
|
| `crates/boot/src/generators/bls.rs`, `crates/bls` | BLS values, boot counting, `loader.conf` |
|
||
|
|
|
||
|
|
## 2. Check each key
|
||
|
|
|
||
|
|
For every struct field in `crates/config`, CONFIG.md needs its TOML name (look at `#[serde(rename)]`, as
|
||
|
|
most multi-word keys use dashes), its type, its default, and what it does. Read the code that uses it in
|
||
|
|
`crates/boot`, not only the doc comment, because the behavior is what the reader depends on.
|
||
|
|
|
||
|
|
Look for the usual drift:
|
||
|
|
|
||
|
|
- a field added, renamed or removed
|
||
|
|
- a default that changed (`#[serde(default = ...)]`, the `Default` impls, constants such as
|
||
|
|
`DEFAULT_MENU_TIMEOUT_SECONDS`)
|
||
|
|
- a new BLS value set with `context.set`, or a new option in `SproutOptions`
|
||
|
|
- a new row to add to, or remove from, the strict mode table
|
||
|
|
- a changed order: the default entry sources, the menu timeout sources, or the phases
|
||
|
|
- `LATEST_VERSION` changing, which the intro and `version` text must follow
|
||
|
|
|
||
|
|
Don't document what you can't confirm in the code. If a behavior is unclear, read the function that
|
||
|
|
implements it.
|
||
|
|
|
||
|
|
## 3. Write the change
|
||
|
|
|
||
|
|
- Keep each section's shape: a short explanation, a TOML example, then a table of keys.
|
||
|
|
- Examples must parse. Check that every key in one exists and is spelled the way serde expects.
|
||
|
|
- Update the table of contents if you add or rename a heading.
|
||
|
|
- Keep README.md short. It gets the feature list and the minimal examples, and CONFIG.md gets everything else.
|
||
|
|
- Don't duplicate the strict mode table or the default entry order anywhere else.
|
||
|
|
|
||
|
|
## 4. Write like a person
|
||
|
|
|
||
|
|
Plain sentences, said once. Skip these:
|
||
|
|
|
||
|
|
- filler like "robust", "seamless", "powerful", "leverage", "ensure", "note that", "it's important to"
|
||
|
|
- groups of three added for rhythm, and a summary sentence at the end of every section
|
||
|
|
- bullet lists for what a sentence says better, and bold used as decoration
|
||
|
|
- em dashes (use a comma, colon or parentheses)
|
||
|
|
|
||
|
|
Say what a setting does and what happens when it's unset or wrong. Name real things (`bootctl`, `PCR 12`,
|
||
|
|
`\EFI\Linux`) instead of describing them.
|
||
|
|
|
||
|
|
## 5. Verify
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cargo build --target x86_64-unknown-uefi
|
||
|
|
cargo build --target aarch64-unknown-uefi
|
||
|
|
cargo fmt --all --check
|
||
|
|
```
|
||
|
|
|
||
|
|
Then re-read the diff of CONFIG.md against the code once more for any key whose name or default you
|
||
|
|
touched. If the change was only to docs, skip the builds.
|