# 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: ```sh #!/bin/sh # Image version # # Prints the build time in UTC (YYYYMMDDhhmm). Every build gets a higher version than the one # before, which is how systemd-sysupdate tells that an update is newer. ``` - 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/sh` with `set -eu`. Switch to `#!/bin/bash` with `set -euo pipefail` only 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.