[hotfix][doc] improve comments in archunit.properties

flink-architecture-tests/flink-architecture-tests-production/src/test/resources/archunit.properties

@@ -16,13 +16,17 @@
 # limitations under the License.
 #
 
-# By default we allow removing existing violations, but fail when new violations are added.
+# This controls if the violation store is writable
 freeze.store.default.allowStoreUpdate=true
 
-# Enable this if a new (frozen) rule has been added in order to create the initial store and record the existing violations.
+# Enable this if a new rule was added or the description of an existing rule has changed.
+# It is needed to record future violations of this rule.
+# If omitted, future violations of the rule will not be considered as violations as the initial store was not created for this rule.
 #freeze.store.default.allowStoreCreation=true
 
-# Enable this to add allow new violations to be recorded.
+# Enable this to record the current state of violations.
+# This can make sense, because current violations are consciously accepted and should be added to the store
+# By default we allow removing existing violations, but fail when new violations are added
 # NOTE: Adding new violations should be avoided when possible. If the rule was correct to flag a new
 #       violation, please try to avoid creating the violation. If the violation was created due to a
 #       shortcoming of the rule, file a JIRA issue so the rule can be improved.

flink-architecture-tests/flink-architecture-tests-test/src/test/resources/archunit.properties

@@ -16,13 +16,17 @@
 # limitations under the License.
 #
 
-# By default we allow removing existing violations, but fail when new violations are added.
+# This controls if the violation store is writable
 freeze.store.default.allowStoreUpdate=true
 
-# Enable this if a new (frozen) rule has been added in order to create the initial store and record the existing violations.
+# Enable this if a new rule was added or the description of an existing rule has changed.
+# It is needed to record future violations of this rule.
+# If omitted, future violations of the rule will not be considered as violations as the initial store was not created for this rule.
 #freeze.store.default.allowStoreCreation=true
 
-# Enable this to add allow new violations to be recorded.
+# Enable this to record the current state of violations.
+# This can make sense, because current violations are consciously accepted and should be added to the store
+# By default we allow removing existing violations, but fail when new violations are added
 # NOTE: Adding new violations should be avoided when possible. If the rule was correct to flag a new
 #       violation, please try to avoid creating the violation. If the violation was created due to a
 #       shortcoming of the rule, file a JIRA issue so the rule can be improved.

flink-connectors/flink-connector-base/src/test/resources/archunit.properties

@@ -16,13 +16,17 @@
 # limitations under the License.
 #
 
-# By default we allow removing existing violations, but fail when new violations are added.
+# This controls if the violation store is writable
 freeze.store.default.allowStoreUpdate=true
 
-# Enable this if a new (frozen) rule has been added in order to create the initial store and record the existing violations.
+# Enable this if a new rule was added or the description of an existing rule has changed.
+# It is needed to record future violations of this rule.
+# If omitted, future violations of the rule will not be considered as violations as the initial store was not created for this rule.
 #freeze.store.default.allowStoreCreation=true
 
-# Enable this to add allow new violations to be recorded.
+# Enable this to record the current state of violations.
+# This can make sense, because current violations are consciously accepted and should be added to the store
+# By default we allow removing existing violations, but fail when new violations are added
 # NOTE: Adding new violations should be avoided when possible. If the rule was correct to flag a new
 #       violation, please try to avoid creating the violation. If the violation was created due to a
 #       shortcoming of the rule, file a JIRA issue so the rule can be improved.