Document what each value in the os workflow is for, link STYLE.md from the README, and match its header example to mkosi.version. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1.3 KiB
1.3 KiB
Style guide
For everyone who changes this repository, people and AI agents alike.
General
- Keep it simple. Prefer fewer files, fewer lines and the defaults. Delete what isn't needed.
- Each fact lives in one place. Elsewhere, refer to it by path instead of repeating it.
- Write plain English in short sentences.
File header
Every file that allows comments starts with a header. It goes after the shebang, if there is one:
#!/bin/sh
# Image version
#
# The build time (UTC), so every build is newer than the last.
- Line 1 is a title: a few words, in sentence case, with no full stop.
- Then a line with only the comment character.
- Then what the file does and why, naming the files it works with by path.
Files that can't hold comments (JSON, subuid, machine-id) are explained in the file that uses
them or in the README.
Comments
- Explain why, not what. Leave out comments that only repeat the code.
- Put a comment right above the line or block it is about.
- Wrap comments at 100 columns.
Shell
- Use
#!/bin/shwithset -eu. Switch to#!/bin/bashwithset -euo pipefailonly when the script needs bash. - Quote variables:
"$var".
Config files
- Put one value per line in lists, with a comment explaining the less obvious entries.