Replace mkosi.prepare with Anthropic's rpm repository (mkosi.sandbox/), switch the workflow to the gitea context, and start STYLE.md with a consistent file header. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
45 lines
1.4 KiB
Markdown
45 lines
1.4 KiB
Markdown
# 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.
|