This is an automated email from the ASF dual-hosted git repository. cbrisson pushed a commit to branch engine-2.4 in repository https://gitbox.apache.org/repos/asf/velocity-site.git
commit 305d101bcb046517ae610d5471a865a95571b8d6 Author: Claude Brisson <[email protected]> AuthorDate: Fri Aug 23 18:35:37 2024 +0200 Revamp the upgrading page: factorize the maximum compatibility section and add runtime.immutable_ranges=false to it --- src/content/engine/devel/upgrading.mdtext | 49 +++++++------------------------ 1 file changed, 11 insertions(+), 38 deletions(-) diff --git a/src/content/engine/devel/upgrading.mdtext b/src/content/engine/devel/upgrading.mdtext index 5e6137e..6a98911 100644 --- a/src/content/engine/devel/upgrading.mdtext +++ b/src/content/engine/devel/upgrading.mdtext @@ -8,9 +8,9 @@ Title: Apache Velocity Engine - Upgrading Release with the same major number (1.x, 2.x) are intended to be drop-in replacements. However, in most cases the versions of dependency jars must be adjusted because newer versions of Velocity might require updates. -## Upgrading from Velocity 2.1 to Velocity 2.2 +## Upgrading from Velocity 1.x to the latest 2.x version for busy people -For busy people: To maximize backward compatibility of Velocity 2.2 with Velocity 1.x, be sure to include the following lines in your Velocity configuration: +To maximize backward compatibility of the last Velocity 2.x with Velocity 1.x, be sure to include the following lines in your Velocity configuration: :::properties # No automatic conversion of methods arguments @@ -37,8 +37,17 @@ For busy people: To maximize backward compatibility of Velocity 2.2 with Velocit # When using an invalid reference handler, also include tested references (since 2.2) event_handler.invalid_references.tested = true + # Let the range operator expressions '[ x..y ]' return mutable lists (since 2.4) + runtime.immutable_ranges = false + Also, please note that since version 2.1, Velocity requires Java JDK 1.8+ for bulding and Java JRE 1.8+ at runtime. +## Upgrading from Velocity 2.2 to Velocity 2.3 + +No specific change needed. + +## Upgrading from Velocity 2.1 to Velocity 2.2 + ### Behavior / API Changes + The references with alternate values like `${foo|'foo'}` won't trigger any invalid reference event if their alternate value is valid. @@ -57,26 +66,6 @@ Also, please note that since version 2.1, Velocity requires Java JDK 1.8+ for bu ## Upgrading from Velocity 2.0 to Velocity 2.1 -For busy people: To maximize backward compatibility of Velocity 2.1 with Velocity 1.x, be sure to include the following lines in your Velocity configuration: - - :::properties - # No automatic conversion of methods arguments - introspector.conversion_handler.class = none - - # Use backward compatible space gobbling - parser.space_gobbling = bc - - # Have #if($foo) only returns false if $foo is false or null - directive.if.empty_check = false - - # Allow '-' in identifiers (since 2.1) - parser.allow_hyphen_in_identifiers = true - - # When displaying null arguments literals, use provided arguments literals (since 2.1, but deprecated in 2.2) - velocimacro.arguments.preserve_literals = true - -Also, please note that Velocity 2.1 now requires Java JDK 1.8+ for bulding and Java JRE 1.8+ at runtime. - ### Behavior / API Changes + inside a macro, since 2.0, the rendering of null arguments uses the local reference literal. To revert to the 1.7 behavior, you can set the boolean property `velocimacro.preserve.arguments.literals` to true. The macros will then use the provided argument literals in such cases. @@ -105,22 +94,6 @@ Please note that the maven repository path has changed: </ul> </div> -For busy people: To maximize backward compatibility of Velocity 2.0 with Velocity 1.x, be sure to include the following lines in your Velocity configuration: - - :::properties - # No automatic conversion of methods arguments - runtime.conversion.handler.class = none - - # Use backward compatible space gobbling - space.gobbling = bc - - # Have #if($foo) only returns false if $foo is false or null - directive.if.emptycheck = false - -and check the [Dependency changes](#dependencies-changes) below. - -Read below for futher details. - ### Behavior / API Changes + velocity is now using the SLF4J logging facade. Hence, all methods accepting or returning a logger now use the org.slf4j.Logger object. Velocity uses a logger name of `org.apache.velocity` (configurable with the `runtime.log.name` configuration entry), and [several other childen loggers](developer-guide.html#logging).
