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 <[email protected]>
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: [email protected]
For additional commands, e-mail: [email protected]
For further information, visit: https://activemq.apache.org/contact
