You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2018/03/13 07:11:35 UTC
incubator-freemarker git commit: Made it more clear that using
Configuration.getVersion() for the value of the incompatibleImprovements
setting is bad idea.
Repository: incubator-freemarker
Updated Branches:
refs/heads/2.3-gae 126161072 -> 40ced2d45
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-gae
Commit: 40ced2d45fcf92723e6db386e13df9161d5a4608
Parents: 1261610
Author: ddekany <dd...@apache.org>
Authored: Tue Mar 13 08:11:25 2018 +0100
Committer: ddekany <dd...@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>