As far as I understand, --release is also a rather confusing flag that was originally (and still is?) only intended for use by “system package maintainers”
For an example of something that might be unexpected, if the preferred_optimize_mode field is set in StandardOptimizeOptionOptions, then the <mode> in --release=<mode> is silently ignored (and this behavior is intentional).
Relevant issues/PRs:
- `--release=x` ignored when `preferred_optimize_mode` is set · Issue #19732 · ziglang/zig · GitHub
- std.Build: fix --release=x when preferred mode set by ifreund · Pull Request #19733 · ziglang/zig · GitHub
- rename `preferred_optimize_mode` to better reflect its usage by xdBronch · Pull Request #20246 · ziglang/zig · GitHub
Personally, I avoid --release/preferred_optimize_mode entirely. Somewhere down the line hopefully this stuff will become less confusing, though (as mentioned in this PR, breaking changes to these APIs in the future are very likely).