What is the purpose of the incompatible_improvements setting?

incompatible_improvements is a version-gated flag, set on the Configuration (for example new Configuration(Configuration.VERSION_2_3_32)), that lets the FreeMarker project fix bugs and inconsistent behaviors, or make the engine stricter, without silently breaking applications that simply drop in a newer freemarker.jar.

Rather than always applying the newest, strictest behavior, FreeMarker checks this flag before applying any change that is not fully backward compatible: if the application sets it to an older version, the old (sometimes buggier or looser) behavior is preserved; setting it to a newer version opts into the corrected or stricter behavior tied to that release. This is the mechanism behind FreeMarker's strong compatibility guarantee that upgrading the jar alone should never change existing template behavior unless this flag is also raised.

New projects are generally advised to set it to the latest version available at the time they start, since there is no reason to inherit older quirks on day one, while long-lived applications typically raise it deliberately, one step at a time, alongside testing.