The issues of `--ignore-promote-rules`

Background

The --ignore-promoted-rules flag was introduced to allow disabling all rules with (mode promote) on them. The idea is that in release mode, such rules aren't meant to be run and the release build should always refer to the promoted targets. To allow users to detect this behavior inside rules, the %{ignoring_promoted_rules} variable was added. This allowed the user to create manual "fallback" rules if the promote rule wasn't available.

Later, it was realized that this flag was mistakenly applied (mode promote-until-clean) rules as well. This was unintended.

We then fixed the behavior with (mode promote-until-clean) but guarded it behind the version inside the dune language.

Later, we discovered that this flag didn't apply to internal rules at all. One example of an internal rule that ignores this is the generation of opam files.

Problems

Because --ignore-promoted-rules was implemented partially, we're left in a somewhat difficult state:

• Many users are currently relying on the current buggy behavior
• Fixing the behavior is impossible in a backwards compatible way

Proposal

There's two things we can do to address this. We can do one of these, or both at once.

Fix --ignore-promoted-rules

That would mean making --ignore-promoted-rules ignore the version in the dune-project and unilaterally ignore all promoted rules. Since this is a breaking change, we must do it in steps. I imagine the following, introduce a new option called --really-ignore-promoted-rules. We also change the new version of dune language (likely 3.12?) to generate this flag.

Eventually, one day we'll unify both options and make them mean the same thing.

But meanwhile, we need to keep both options so that we can explicitly set in packages that rely on one particular behavior if we switch the default implied by --release.

Introduce --fallback-promoted-rules

We start with the observation that changing all rules with (mode promote) to (mode fallback) in release mode is a far more backwards compatible change that somewhat preserves the original intention of this behavior. Fallback rules are already ignored when their targets are present in the source tree.

So as a first step, we can introduce this command line option and make it an alternative to --fallback-promoted-rules.

In the newest version of dune, we can generate opam files that make use of this option instead of --ignore-promoted-rules.

Setting this option should not make %{ignoring_promoted_rules} true. This was a mistake in our initial implementation and it will simply add to the confusion.

Once we've given users some time to transition, we can make this option the default implied by --release. If there's anyone that needs the old behavior, we can modify their opam files to explicit include --ignore-promoted-rules to restore it.

Whatever choice we make, we need to include a section about this in the manual so that users know exactly which option they need.

Start by tracing the existing --ignore-promoted-rules handling, including its treatment of promote, promote-until-clean, and internal rules. Review release-mode opam file generation and the manual's option documentation. Done means agreeing on the compatibility path, implementing the selected option behavior, updating generated opam files, and documenting the transition.