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 <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">&lt;init-param&gt;
     &lt;param-name&gt;incompatible_improvements&lt;/param-name&gt;
-    &lt;param-value&gt;2.3.27&lt;/param-value&gt;
+    &lt;param-value&gt;2.3.28&lt;/param-value&gt;
 &lt;/init-param&gt;</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>

Reply via email to