From d191f7cf7e9411c66a905d0fdc7a4ed70f1bea4c Mon Sep 17 00:00:00 2001
From: "Zaiming (Stone) Shi" <zmstone@gmail.com>
Date: Thu, 30 Dec 2021 18:36:26 +0100
Subject: [PATCH 1/2] chore: update to hocon 0.22.2

---
 apps/emqx/rebar.config | 2 +-
 rebar.config           | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/emqx/rebar.config b/apps/emqx/rebar.config
index 18e4f0e1f..6678f3ab4 100644
--- a/apps/emqx/rebar.config
+++ b/apps/emqx/rebar.config
@@ -17,7 +17,7 @@
     , {esockd, {git, "https://github.com/emqx/esockd", {tag, "5.9.0"}}}
     , {ekka, {git, "https://github.com/emqx/ekka", {tag, "0.11.2"}}}
     , {gen_rpc, {git, "https://github.com/emqx/gen_rpc", {tag, "2.5.1"}}}
-    , {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.22.0"}}}
+    , {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.22.2"}}}
     , {pbkdf2, {git, "https://github.com/emqx/erlang-pbkdf2.git", {tag, "2.0.4"}}}
     , {recon, {git, "https://github.com/ferd/recon", {tag, "2.5.1"}}}
     , {snabbkaffe, {git, "https://github.com/kafka4beam/snabbkaffe.git", {tag, "0.16.0"}}}
diff --git a/rebar.config b/rebar.config
index 9cb84e00b..579e91573 100644
--- a/rebar.config
+++ b/rebar.config
@@ -65,7 +65,7 @@
     , {system_monitor, {git, "https://github.com/k32/system_monitor", {tag, "2.2.1"}}}
     , {getopt, "1.0.2"}
     , {snabbkaffe, {git, "https://github.com/kafka4beam/snabbkaffe.git", {tag, "0.16.0"}}}
-    , {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.22.0"}}}
+    , {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.22.2"}}}
     , {emqx_http_lib, {git, "https://github.com/emqx/emqx_http_lib.git", {tag, "0.4.1"}}}
     , {esasl, {git, "https://github.com/emqx/esasl", {tag, "0.2.0"}}}
     , {jose, {git, "https://github.com/potatosalad/erlang-jose", {tag, "1.11.2"}}}

From d88a6480920fca0b891394a5e07b1a55823d7522 Mon Sep 17 00:00:00 2001
From: "Zaiming (Stone) Shi" <zmstone@gmail.com>
Date: Thu, 30 Dec 2021 18:36:42 +0100
Subject: [PATCH 2/2] docs: update config doc

Explain layered style at the very top of the doc
---
 apps/emqx_conf/etc/emqx_conf.md | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/apps/emqx_conf/etc/emqx_conf.md b/apps/emqx_conf/etc/emqx_conf.md
index f68411bff..1d60de568 100644
--- a/apps/emqx_conf/etc/emqx_conf.md
+++ b/apps/emqx_conf/etc/emqx_conf.md
@@ -2,6 +2,20 @@ EMQ X configuration file is in [HOCON](https://github.com/emqx/hocon) format.
 HOCON, or Human-Optimized Config Object Notation is a format for human-readable data,
 and a superset of JSON.
 
+## Layered
+
+EMQ X configuration consists of 3 layers.
+From bottom up:
+
+1. Immutable base: `emqx.conf` + `EMQX_` prfixed environment variables.<br>
+   Changes in this layer require a full node restart to take effect.
+1. Cluster override: The path of which is configured by `cluster_override_conf_file`.<br>
+   Overrides made from management APIs (or dashboard) for all nodes in the cluster.
+1. Local override: The path of which is configured by `local_override_conf_file`.<br>
+   Special overrides applied to local node.
+
+For detailed override rules, see [Config overlay rules](#config-overlay-rules).
+
 ## Syntax
 
 In config file the values can be notated as JSON like ojbects, such as
@@ -12,7 +26,7 @@ node {
 }
 ```
 
-Another equivalent representation is flat, suh as
+Another equivalent representation is flat, such as
 
 ```
 node.name="127.0.0.1"
@@ -117,17 +131,14 @@ because the field name is `enable`, not `enabled`.
 
 <strong>NOTE:</strong> Unknown root keys are however silently discarded.
 
-### Config overlay
+### Config overlay rules
 
-HOCON values are overlayed, earlier defined values are at layers closer to the bottom.
-The overall order of the overlay rules from bottom up are:
+HOCON objects are overlayed, in general:
 
-1. `emqx.conf` the base config file
-1. `EMQX_` prfixed environment variables
-1. Cluster override file, the path of which is configured as `cluster_override_conf_file` in the lower layers
-1. Local override file, the path of which is configured as `local_override_conf_file` in the lower layers
+- Within one file, objects defined 'later' recursively override objects defined 'earlier'
+- When layered, 'later' (hihger lalyer) objects override objects defined 'earlier' (lower layer)
 
-Below are the rules of config value overlay.
+Below are more detailed rules.
 
 #### Struct Fileds