(activemq-artemis) branch main updated: ARTEMIS-5056 clarify docs on 'default' values

[cl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

clebertsuconic pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git


The following commit(s) were added to refs/heads/main by this push:
     new 8d63f4b9d6 ARTEMIS-5056 clarify docs on 'default' values
8d63f4b9d6 is described below

commit 8d63f4b9d6c78ecaee959b97c69707571ced6bd7
Author: Justin Bertram <jb...@apache.org>
AuthorDate: Tue Apr 1 10:14:58 2025 -0500

    ARTEMIS-5056 clarify docs on 'default' values
---
 docs/user-manual/address-settings.adoc    |  4 ++--
 docs/user-manual/configuration-index.adoc | 21 ++++++++++++++-------
 2 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/docs/user-manual/address-settings.adoc b/docs/user-manual/address-settings.adoc
index ba197f8697..33f81080e5 100644
--- a/docs/user-manual/address-settings.adoc
+++ b/docs/user-manual/address-settings.adoc
@@ -270,7 +270,7 @@ include::_auto-queue-creation-note.adoc[]
 
 auto-delete-queues::
 Whether or not the broker should automatically delete auto-created queues when they have both 0 consumers and the message count is  less than or equal to `auto-delete-queues-message-count`.
-Default is `true`.
+Default is xref:configuration-index.adoc#regarding-default-values[`true`].
 
 auto-delete-created-queues::
 Whether or not the broker should automatically delete created queues when they have both 0 consumers and the message count is  less than or equal to `auto-delete-queues-message-count`.
@@ -319,7 +319,7 @@ The core API is a low-level API and is not meant to have such automation.
 
 auto-delete-addresses::
 Whether or not the broker should automatically delete auto-created addresses once the address no longer has any queues.
-Default is `true`.
+Default is xref:configuration-index.adoc#regarding-default-values[`true`].
 
 auto-delete-addresses-delay::
 How long to wait (in milliseconds) before deleting auto-created addresses after they no longer have any queues.
diff --git a/docs/user-manual/configuration-index.adoc b/docs/user-manual/configuration-index.adoc
index 9df8d51646..ed130a8263 100644
--- a/docs/user-manual/configuration-index.adoc
+++ b/docs/user-manual/configuration-index.adoc
@@ -129,13 +129,20 @@ This describes the root of the XML configuration.
 You will see here also multiple sub-types listed.
 For example on the main config you will have bridges and at the <<bridge-type,list of bridge>> type we will describe the properties for that configuration.
 
-[WARNING]
-====
-The default values listed below are the values which will be used if the configuration parameter is *not set* either programmatically or via `broker.xml`.
-Some of these values are set in the `broker.xml` which is available out-of-the-box.
-Any values set in the out-of-the-box configuration will override the default values listed here.
-Please consult your specific configuration to know which values will actually be used when the broker is running.
-====
+[[regarding-default-values]]
+.Regarding _default_ Values
+****
+The documentation often refers to the _default_ values.
+This is the value of a configuration attribute if it is *not set* (e.g. programmatically, via XML, etc.).
+
+This is worth noting because a `broker.xml` is generated automatically when a xref:using-server.adoc#creating-a-broker-instance[broker instance is created] and this out-of-the-box `broker.xml` may have configuration values which may differ from and override the default values identified here.
+This is relatively rare, but it normally happens when we've discovered that a default is not actually suitable for most use-cases.
+
+Changing the actual default value cannot be done in a minor release as dictated by https://semver.org/[semantic versioning] so we have to wait for a major release to make such changes.
+However, in the mean-time we can address unsuitable defaults by modifying the generated `broker.xml` which maintains backwards compatibility for existing broker instances while giving new deployments an updated configuration.
+
+In general, it's recommended that you consult your specific configuration to know which values will actually be used when the broker is running.
+****
 
 |===
 | Name | Description | Default


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@activemq.apache.org
For additional commands, e-mail: commits-help@activemq.apache.org
For further information, visit: https://activemq.apache.org/contact