Repository: incubator-freemarker Updated Branches: refs/heads/3 f22494599 -> 36b33752e
Forward ported from 2.3-gae: 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/36b33752 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/36b33752 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/36b33752 Branch: refs/heads/3 Commit: 36b33752ebc79ac7c9164b52087ba6434f7af7aa Parents: f224945 Author: ddekany <ddek...@apache.org> Authored: Tue Mar 13 08:11:55 2018 +0100 Committer: ddekany <ddek...@apache.org> Committed: Tue Mar 13 08:11:55 2018 +0100 ---------------------------------------------------------------------- .../java/org/apache/freemarker/core/Configuration.java | 13 +++++++++---- .../apache/freemarker/core/TopLevelConfiguration.java | 7 +++++-- 2 files changed, 14 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/36b33752/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java b/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java index f0f3285..b0043c6 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java @@ -1574,10 +1574,12 @@ public final class Configuration implements TopLevelConfiguration, CustomStateSc /** * @param incompatibleImprovements - * The initial value of the - * {@link Configuration#getIncompatibleImprovements() incompatibleImprovements}; can't {@code null}. - * This can be later changed via {@link #setIncompatibleImprovements(Version)}. The point here is - * just to ensure that it's never {@code null}. + * The initial value of the {@link Configuration#getIncompatibleImprovements() + * incompatibleImprovements}; can't {@code null}. This can be later changed via + * {@link #setIncompatibleImprovements(Version)}. The point here is just to ensure that it's never + * {@code null}. Do NOT ever use {@link Configuration#getVersion()} to set this. Always use a fixed + * value, like {@link #VERSION_3_0_0}, otherwise your application can break as you upgrade + * FreeMarker. */ protected ExtendableBuilder(Version incompatibleImprovements) { _NullArgumentException.check("incompatibleImprovements", incompatibleImprovements); @@ -2346,6 +2348,9 @@ public final class Configuration implements TopLevelConfiguration, CustomStateSc /** * Setter pair of {@link Configuration#getIncompatibleImprovements()}. + * + * <p>Do NOT ever use {@link Configuration#getVersion()} to set the "incompatible improvements". Always use + * a fixed value, like {@link #VERSION_3_0_0}. Otherwise your application can break as you upgrade FreeMarker. * * <p>This is not called from the {@link ExtendableBuilder#ExtendableBuilder(Version)}; the initial value is set * without this. http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/36b33752/freemarker-core/src/main/java/org/apache/freemarker/core/TopLevelConfiguration.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/TopLevelConfiguration.java b/freemarker-core/src/main/java/org/apache/freemarker/core/TopLevelConfiguration.java index f6b4fbb..453d1fa 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/TopLevelConfiguration.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/TopLevelConfiguration.java @@ -171,8 +171,8 @@ public interface TopLevelConfiguration extends ParsingAndProcessingConfiguration /** * Returns the value of the "incompatible improvements" setting; this 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 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 below), at + * new projects you should set this to the fixed 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 below), at * least 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 always low * risk. @@ -180,6 +180,9 @@ public interface TopLevelConfiguration extends ParsingAndProcessingConfiguration * 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 Configuration#getVersion()} to set the "incompatible improvements". Always use a fixed + * value, like {@link Configuration#VERSION_3_0_0}. 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 3.0.1, but accidentally the * application is deployed with FreeMarker 3.0.0, then FreeMarker will fail, telling that a higher version is
