I wrote this on the PR but I think here is better:

This is already working as designed, although clearly the flag names do not make this self-evident. How it currently stands is that there are two parties communicating their preference to the build system:

• upstream maintainer communicates preference via preferred_optimize_mode when calling standardOptimizeOption.
• the person running zig build communicates default preference via --release flag.

The build system gives the upstream maintainer's preference priority of these two options. However, the application may also expose additional options. --release is intended to be globally set by the distribution in the package management code, for example maybe they hard-code --release=safe as the global default. Meanwhile, any particular project may expose more fine-grained options, including perhaps the familiar -Doptimize flag, which take the most precedence of all and will override --release.

--release is intended to be globally set by the distribution in the package management code

if this is true I think the issue should stand and the upstream's preferences should never take priority over this flag. imo it should go

1. -Doptimize/-Dmode
2. --release=X
3. preferred_optimize_mode

preferred_optimize_mode should only be taken if a bare --release with no preference given is put

(Moving my comment from IRC.)
I suspect the sensible way to do this is to rename "preferred" to "override" or "force" or something similar and emit a warning onto stderr when --release is ignored. Possibly with an additional actual "preferred" to be used when --release isn't given (or we get a bare release without an argument)?

Another alternative: Remove --release=x and only support --release. That makes the flag a very basic request from the caller: "I'm building this package for release". The package maintainer is the best person to set sensible defaults for this scenario. If the caller also wants to make more fine-tuned tweaks, then they need to get into -Doptimize and/or other flags and really understand the build system for this particular project.