(velocity-site) 02/02: Revamp the upgrading page: factorize the maximum compatibility section and add runtime.immutable_ranges=false to it

[cb...@apache.org]

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 <cl...@renegat.net>
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).