Made it more clear that using Configuration.getVersion() for the value of the incompatibleImprovements setting is bad idea.
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/40ced2d4 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/40ced2d4 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/40ced2d4 Branch: refs/heads/2.3 Commit: 40ced2d45fcf92723e6db386e13df9161d5a4608 Parents: 1261610 Author: ddekany <ddek...@apache.org> Authored: Tue Mar 13 08:11:25 2018 +0100 Committer: ddekany <ddek...@apache.org> Committed: Tue Mar 13 08:11:25 2018 +0100 ---------------------------------------------------------------------- .../java/freemarker/template/Configuration.java | 19 +++++++--- src/manual/en_US/book.xml | 37 ++++++++++++++------ 2 files changed, 41 insertions(+), 15 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/40ced2d4/src/main/java/freemarker/template/Configuration.java ---------------------------------------------------------------------- diff --git a/src/main/java/freemarker/template/Configuration.java b/src/main/java/freemarker/template/Configuration.java index 3673272..5f35435 100644 --- a/src/main/java/freemarker/template/Configuration.java +++ b/src/main/java/freemarker/template/Configuration.java @@ -547,8 +547,8 @@ public class Configuration extends Configurable implements Cloneable, ParserConf * <p><b>About the "incompatible improvements" setting</b> * * <p>This setting value is the FreeMarker version number where the not 100% backward compatible bug fixes and - * improvements that you want to enable were already implemented. In new projects you should set this to the - * version of FreeMarker that you start the development with. In older projects it's also usually better to keep + * improvements that you want to enable were already implemented. In new projects you should set this to the fixed + * FreeMarker version that you start the development with. In older projects it's also usually better to keep * this high, however you should check the changes activated (find them below), especially if not only the 3rd * version number (the micro version) of {@code incompatibleImprovements} is increased. Generally, as far as you * only increase the last version number of this setting, the changes are low risk. The default value is 2.3.0 to @@ -557,6 +557,9 @@ public class Configuration extends Configurable implements Cloneable, ParserConf * <p>Bugfixes and improvements that are fully backward compatible, also those that are important security fixes, * are enabled regardless of the incompatible improvements setting. * + * <p>Do NOT ever use {@link #getVersion()} to set the "incompatible improvements". Always use a fixed value, like + * {@link #VERSION_2_3_28}. Otherwise your application can break as you upgrade FreeMarker. + * * <p>An important consequence of setting this setting is that now your application will check if the stated minimum * FreeMarker version requirement is met. Like if you set this setting to 2.3.22, but accidentally the application * is deployed with FreeMarker 2.3.21, then FreeMarker will fail, telling that a higher version is required. After @@ -1865,7 +1868,11 @@ public class Configuration extends Configurable implements Cloneable, ParserConf /** * Use {@link #Configuration(Version)} instead if possible; see the meaning of the parameter there. - * If the default value of a setting depends on the {@code incompatibleImprovements} and the value of that setting + * + * <p>Do NOT ever use {@link #getVersion()} to set the "incompatible improvements". Always use a fixed value, like + * {@link #VERSION_2_3_28}. Otherwise your application can break as you upgrade FreeMarker. + * + * <p>If the default value of a setting depends on the {@code incompatibleImprovements} and the value of that setting * was never set in this {@link Configuration} object through the public API, its value will be set to the default * value appropriate for the new {@code incompatibleImprovements}. (This adjustment of a setting value doesn't * count as setting that setting, so setting {@code incompatibleImprovements} for multiple times also works as @@ -3393,7 +3400,11 @@ public class Configuration extends Configurable implements Cloneable, ParserConf } /** - * Returns the FreeMarker version information, most importantly the major.minor.micro version numbers. + * Returns FreeMarker version information, most importantly the major.minor.micro version numbers; + * do NOT use this as the value of the {@code incompatible_improvements} setting (as the parameter to + * {@link Configuration#Configuration(Version)}), as then your application can break when you upgrade FreeMarker! + * Use a constant value, like {@link #VERSION_2_3_28}, to protect your application from fixes/changes that aren't + * entirely backward compatible. Fixes and features that are backward compatible are always enabled. * * On FreeMarker version numbering rules: * <ul> http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/40ced2d4/src/manual/en_US/book.xml ---------------------------------------------------------------------- diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml index 3bd2562..3d8e321 100644 --- a/src/manual/en_US/book.xml +++ b/src/manual/en_US/book.xml @@ -10043,17 +10043,21 @@ cfg.setNumberFormat("@ua 0.####;; roundingMode=halfUp");</programlisting> implemented. Usually, it's a bad idea to left it on its default, which is 2.3.0 (maximum backward compatibility).</para> - <para>In new projects you should set this to the FreeMarker version - that you are actually using. In older projects it's also usually - better to keep this high, however you better check the changes - activated (find them in <link + <para>In new projects you should set this to the fixed FreeMarker + version (like <literal>Configuration.VERSION_2_3_28</literal>) that + you are actually using when starting the project. In older projects + it's also usually better to keep this high , however you should + check the changes activated (find them in <link xlink:href="https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#Configuration-freemarker.template.Version-";>the API JavaDoc of the <literal>Configuration(Version)</literal> - constructor</link>), at least if not only the 3rd version number + constructor</link>), especially if not only the 3rd version number (the micro version) of <quote>incompatible improvements</quote> setting is increased. Generally, as far as you only increase the - last version number of this setting, the changes are low - risk.</para> + last (3rd) version number of this setting, the changes are low risk, + and whether you can afford that risk depends on the concrete + application. Never use a dynamic value like + <literal>Configuration.getVersion()</literal> though, as that way + upgrading FreeMarker can break your application!</para> <para>Bug fixes and improvements that are fully backward compatible, also those that are important security fixes, are enabled regardless @@ -10081,14 +10085,14 @@ cfg.setNumberFormat("@ua 0.####;; roundingMode=halfUp");</programlisting> <literal>freemarker.template.Configuration</literal> object like:</para> - <programlisting role="unspecified">... = new Configuration(Configuration.VERSION_2_3_27)</programlisting> + <programlisting role="unspecified">... = new Configuration(Configuration.VERSION_2_3_28)</programlisting> </listitem> <listitem> <para>Or, alter the <literal>Configuration</literal> singleton where you initialize its other settings like:</para> - <programlisting role="unspecified">cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_27)</programlisting> + <programlisting role="unspecified">cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_28)</programlisting> </listitem> <listitem> @@ -10096,7 +10100,7 @@ cfg.setNumberFormat("@ua 0.####;; roundingMode=halfUp");</programlisting> (<literal>*.properties</literal> file or <literal>java.util.Properties</literal> object), add:</para> - <programlisting role="unspecified">incompatible_improvements=2.3.27</programlisting> + <programlisting role="unspecified">incompatible_improvements=2.3.28</programlisting> </listitem> <listitem> @@ -10107,7 +10111,7 @@ cfg.setNumberFormat("@ua 0.####;; roundingMode=halfUp");</programlisting> <programlisting role="unspecified"><init-param> <param-name>incompatible_improvements</param-name> - <param-value>2.3.27</param-value> + <param-value>2.3.28</param-value> </init-param></programlisting> </listitem> </itemizedlist> @@ -10139,6 +10143,17 @@ cfg.setNumberFormat("@ua 0.####;; roundingMode=halfUp");</programlisting> <literal>DefaultObjectWrapper</literal> (for <literal>BeansWrapper</literal> it's the same, only with different class name of course).</para> + + <warning> + <para>Do not ever use + <literal>Configuration.getVersion()</literal> to set the + <quote>incompatible improvements</quote> setting. Always use a + fixed value, like <literal>Configuration.VERSION_2_3_28</literal>. + Otherwise your application can break as you upgrade FreeMarker. + The whole point of <quote>incompatible improvements</quote> is to + protect you from that, while you still always get the + fixes/improvements that are backward compatible.</para> + </warning> </section> </section> </chapter>
