ARTEMIS-4081, ARTEMIS-4020: update versions/update docs around new upgrade helper tool, and refresh existing manual update step diffs for subsequent change

docs/user-manual/en/02-27-00-scripts-profiles-windows.diff

@@ -40,7 +40,7 @@ diff --git a/broker-instance/bin/artemis.cmd b/broker-instance/bin/artemis.cmd
 index 2d39231708..ed7ea68955 100644
 --- a/broker-instance/bin/artemis.cmd
 +++ b/broker-instance/bin/artemis.cmd
-@@ -48,10 +48,6 @@ rem "Load Profile Config"
+@@ -48,13 +48,9 @@ rem "Load Profile Config"
  set ARTEMIS_INSTANCE_ETC="${artemis.instance.etc}"
  call %ARTEMIS_INSTANCE_ETC%\artemis.profile.cmd %*
  
@@ -48,10 +48,15 @@ index 2d39231708..ed7ea68955 100644
 -set ARTEMIS_LOGGING_CONF=%ARTEMIS_INSTANCE_ETC_URI%/logging.properties
 -set ARTEMIS_LOG_MANAGER=org.jboss.logmanager.LogManager
 -
- if not exist "%ARTEMIS_OOME_DUMP%" goto NO_ARTEMIS_OOME_DUMP
+-if not exist "%ARTEMIS_OOME_DUMP%" goto NO_ARTEMIS_OOME_DUMP
++if not exist %ARTEMIS_OOME_DUMP% goto NO_ARTEMIS_OOME_DUMP
  rem "Backup the last OOME heap dump"
- move /Y "%ARTEMIS_OOME_DUMP%" "%ARTEMIS_OOME_DUMP%.bkp"
+-move /Y "%ARTEMIS_OOME_DUMP%" "%ARTEMIS_OOME_DUMP%.bkp"
-@@ -66,8 +62,6 @@ set JVM_ARGS=%JVM_ARGS% -Dartemis.home=%ARTEMIS_HOME%
++move /Y %ARTEMIS_OOME_DUMP% %ARTEMIS_OOME_DUMP%.bkp
+ 
+ :NO_ARTEMIS_OOME_DUMP
+ 
+@@ -66,11 +62,10 @@ set JVM_ARGS=%JVM_ARGS% -Dartemis.home=%ARTEMIS_HOME%
  set JVM_ARGS=%JVM_ARGS% -Dartemis.instance=%ARTEMIS_INSTANCE%
  set JVM_ARGS=%JVM_ARGS% -Ddata.dir=%ARTEMIS_DATA_DIR%
  set JVM_ARGS=%JVM_ARGS% -Dartemis.instance.etc=%ARTEMIS_INSTANCE_ETC%
@@ -60,6 +65,11 @@ index 2d39231708..ed7ea68955 100644
  set JVM_ARGS=%JVM_ARGS% -Dartemis.default.sensitive.string.codec.key=%ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY%
  
  if not "%DEBUG_ARGS%"=="" set JVM_ARGS=%JVM_ARGS% %DEBUG_ARGS%
++if not "%$JAVA_ARGS_APPEND%"=="" set JVM_ARGS=%JVM_ARGS% %$JAVA_ARGS_APPEND%
+ 
+ "%_JAVACMD%" %JVM_ARGS% org.apache.activemq.artemis.boot.Artemis %*
+ 
+
 diff --git a/broker-instance/etc/artemis.profile.cmd b/broker-instance/etc/artemis.profile.cmd
 index 5367e34fe4..c4ebbff04a 100644
 --- a/broker-instance/etc/artemis.profile.cmd

docs/user-manual/en/02-27-00-scripts-profiles.diff

@@ -43,7 +43,7 @@ index 4f8e2f3b66..5ee4f1e3a0 100755
      -Djava.security.auth.login.config="$ARTEMIS_INSTANCE_ETC/login.config" \
      $ARTEMIS_CLUSTER_PROPS \
      -classpath "$CLASSPATH" \
-@@ -132,8 +112,6 @@ exec "$JAVACMD" \
+@@ -132,8 +112,7 @@ exec "$JAVACMD" \
      -Djava.io.tmpdir="$ARTEMIS_INSTANCE/tmp" \
      -Ddata.dir="$ARTEMIS_DATA_DIR" \
      -Dartemis.instance.etc="$ARTEMIS_INSTANCE_ETC" \
@@ -51,4 +51,5 @@ index 4f8e2f3b66..5ee4f1e3a0 100755
 -    -Dlogging.configuration="$ARTEMIS_LOGGING_CONF" \
      -Dartemis.default.sensitive.string.codec.key="$ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY" \
      $DEBUG_ARGS \
++    $JAVA_ARGS_APPEND \
      org.apache.activemq.artemis.boot.Artemis "$@"

docs/user-manual/en/upgrading.md

@@ -49,22 +49,34 @@ the value of this property to the location of the new broker home. Please refer
 to the aforementioned [versions](versions.md) document for additional upgrade
 steps (if required).
 
-It is also possible to do these steps automatically as it can be seen in the next section.
+It is also possible to do many of these update steps automatically as can be seen in the next section.
 
 ## Upgrading tool
 
-An automatic approach can be used to upgrade the instance. You may simply call `./artemis upgrade <old-instance>`.
+An upgrade helper tool from the new broker download can be used to refresh various configuration files
+and scripts from an existing broker instance from a prior version, and thus automate much of work to upgrade
+the instance to use the new version.
+
+> You should back up your existing broker instance before running the command.
 
 ```shell
 cd $NEW_ARTEMIS_DOWNLOAD/bin/
 ./artemis upgrade PATH_TO_UPGRADING_INSTANCE
 ```
 
-artemis, artemis.profile will be updated to the new version.
+The broker instance `bin/artemis` script and `etc/artemis.profile`(artemis.cmd and artemis.cmd.profile on Windows)
+will be updated to the new versions, setting its ARTEMIS_HOME to refer to the new broker version home path. The tool
+will also create the new `<instance>/etc/log4j2.properties` configuration file if needed (e.g if you are migrating
+from a version prior to 2.27.0), and remove the old `<instance>/etc/logging.properties` file if present.
 
-The tool will also update log4j2.properties (if you are migrating from a version previous to 2.27.0).
+The broker.xml file and data are retained as-is.
 
 > **Note:**
 >
->Eventual customizations to your scripts will be lost, however the script will copy the older version at a created old-config-bkp folder.
+> Most existing customisations to the old configuration files and scripts will be lost in the process of refreshing the
-
+> files. As such you should compare the old configuration files with the refreshed ones and then port any missing
+> customisations you may have made as necessary. The upgrade command itself will copy the older files it changes to
+> an old-config-bkp.<index> folder within the instance dir.
+>
+> Similarly, if you had customised the old logging.properties file you may need to prepare analogous changes for the
+> new log4j2.properties file.

docs/user-manual/en/versions.md

@@ -12,7 +12,7 @@ This chapter provides the following information for each release:
 [Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12352246&projectId=12315920)
 
 Highlights:
-- 2.27.0 Introduced a new upgrade tool to help migrating your instance to a newer version. Simply use `./artemis upgrade <path-to-your-instance>` from the new downloaded broker.
+- 2.27.0 Introduced a new [upgrade tool](upgrading.md#upgrading-tool) to help migrating your instance to a newer version.
 - The client and broker now use [SLF4J](https://www.slf4j.org/) for their logging API.
 - The broker distribution now uses [Log4J 2](https://logging.apache.org/log4j/2.x/manual/) as its logging implementation.
 
@@ -24,20 +24,41 @@ for more information plus an example around using Log4J 2.
 
 The broker distribution now includes and configures Log4J 2 as its logging implementation, see [logging](logging.md)
 for more details. If upgrading an existing broker instance rather than creating a new instance, some configuration
-etc updates will be necessary for the brokers existing instance /etc and /bin files:
+etc updates will be necessary for the brokers existing instance /etc and /bin files.
+
+You can use the new [upgrade helper tool](upgrading.md#upgrading-tool) from the newly downloaded broker to refresh various
+configuration files and scripts for an existing broker instance. The broker.xml and data are left in place as-is.
+
+> You should back up your existing broker instance before running the command.
+
+The command can be executed by running `./artemis upgrade <path-to-your-instance>` from the new downloaded broker home.
+
+> **Note:**
+>
+> Most existing customisations to the old configuration files and scripts will be lost in the process of refreshing the
+> files. As such you should compare the old configuration files with the refreshed ones and then port any missing
+> customisations you may have made as necessary. The upgrade command itself will copy the older files it changes to
+> an old-config-bkp.<index> folder within the instance dir.
+>
+> Similarly, if you had customised the old logging.properties file you may need to prepare analogous changes for the
+> new log4j2.properties file.
+
+Note also that brokers `configuration-file-refresh-period` broker.xml setting no longer covers logging configuration refresh.
+Log4J 2 has its own configuration reload handling, configured via the `monitorInterval` property within the Log4J
+configuration file itself. The default `<instance>/etc/log4j2.properties` file created has a 5 second monitorInterval
+value set to align with the prior default broker behaviour.
+
+###### Manual update
+Alternatively, rather than using the upgrade helper command as outlined above, you can instead perform the update manually,
+following the [general upgrading procedure](upgrading.md#general-upgrade-procedure) plus the additional steps below:
 
  1. The new `<instance>/etc/log4j2.properties` file should be created with Log4J 2 configuration. The file
     used by the "artemis create" CLI command can be downloaded from:
     [log4j2.properties](https://github.com/apache/activemq-artemis/blob/2.27.0/artemis-cli/src/main/resources/org/apache/activemq/artemis/cli/commands/etc/log4j2.properties)
  2. The old `<instance>/etc/logging.properties` JBoss Logging configuration file should be deleted.
- 3. Related startup script or profile cleanups are needed: a diff file demonstrating the removals needed
+ 3. Related startup script or profile cleanups are needed: a diff file demonstrating the changes needed since 2.26.0
     is available [here](02-27-00-scripts-profiles.diff) for \*nix or [here](02-27-00-scripts-profiles-windows.diff) for Windows.
 
-Note also that brokers `configuration-file-refresh-period` setting no longer covers logging configuration refresh.
-Log4J 2 has its own configuration reload handling, configured via the `monitorInterval` property within the Log4J
-configuration file itself. The default `<instance>/etc/log4j2.properties` file created has a 5 second monitorInterval
-value set to align with the prior default broker behaviour.
-
 ## 2.26.0
 [Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12352297&projectId=12315920)