From 59ffae089c7ce9e6b862870ba2228cf8454b8792 Mon Sep 17 00:00:00 2001
From: deadc0de6 <info@deadc0de.ch>
Date: Tue, 11 Aug 2020 16:08:28 +0200
Subject: [PATCH] update contrib

---
 CONTRIBUTING.md     | 67 ++++++++++++++++++++++++++++-----------------
 dotdrop/cfg_yaml.py | 41 ---------------------------
 2 files changed, 42 insertions(+), 66 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 28d3d0f..5b10c66 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,7 +41,25 @@ The configuration file (yaml) is parsed in two layers:
 
 Only the higher layer is accessible to other classes of dotdrop.
 
-The lower layer part is only taking care of basic types and
+**Rules**
+
+* `dynvariables` are executed in their own config file
+* profile cannot include profiles defined above in the import tree
+* config files do not have access to variables
+  defined above in the import tree
+
+**Precedence**
+
+* `dynvariables` > `variables`
+* profile `(dyn)variables` > any other `(dyn)variables`
+* profile `(dyn)variables` > profile's included `(dyn)variables`
+* imported `variables`/`dynvariables` > `(dyn)variables`
+* actions/transformations  using variables are resolved at runtime
+  (when action/transformation is executed) and not when loading the config
+
+## lower layer (cfg_yaml.py)
+
+The lower layer part is only taking care of basic types
 does the following:
   * normalize all config entries
     * resolve paths (dotfiles src, dotpath, etc)
@@ -55,9 +73,11 @@ does the following:
   * fix any deprecated entries (link_by_default, etc)
   * clear empty entries
 
-In the end it makes sure the dictionary (or parts of it) accessed
+In the end it makes sure the dictionary accessed
 by the higher layer is clean and normalized.
 
+## higher layer (cfg_aggregator.py)
+
 The higher layer will transform the dictionary parsed by the lower layer
 into objects (profiles, dotfiles, actions, etc).
 The higher layer has no notion of inclusion (profile included for example) or
@@ -74,36 +94,33 @@ example) won't be *seen* by the higher layer until the config is reloaded. Consi
 `dirty` flag as a sign the file needs to be written and its representation in higher
 levels in not accurate anymore.
 
-## Variables resolution
+## Variables resolution in the config file
 
-How variables are resolved (pass through jinja2's
-templating function) in the config file.
+How variables are resolved (through jinja2's
+templating) in the config file.
 
-* resolve `include` (the below merge is temporary just to resolve the `includes`)
-  * `variables` and `dynvariables` are first merged and recursively resolved
+* resolve main config file variables
+  * `variables` and `dynvariables` are recursively templated
   * `dynvariables` are executed
-  * they are all merged and `include` paths are resolved
+  * both `variables` and `dynvariables` are merged
+  * profile's `variables` and `dynvariables` are merged
+* resolve *included* entries (see below)
+  * paths and entries are templated
     (allows to use something like `include {{@@ os @@}}.variables.yaml`)
-* `variables` and profile's `variables` are merged
-* `dynvariables` and profile's `dynvariables` are merged
-* `dynvariables` are executed
-* they are all merged into the final *local* `variables`
+* *included* entries are processed
+  * dyn-/variables are all resolved in their own file
 
-These are then used to resolve different elements in the config file:
+*included*
+
+* entry *import_actions*
+* entry *import_configs*
+* entry *import_variables*
+* profile's *import*
+* profile's *include
+
+Variables are then used to resolve different elements in the config file:
 see [this](https://github.com/deadc0de6/dotdrop/wiki/config-variables#config-available-variables)
 
-Then additional variables (`import_variables` and `import_configs`) are
-then merged and take precedence over local variables.
-
-Note:
-
-* `dynvariables` > `variables`
-* profile `(dyn)variables` > any other `(dyn)variables`
-* profile `(dyn)variables` > profile's included `(dyn)variables`
-* imported `variables`/`dynvariables` > `(dyn)variables`
-* actions/transformations  using variables are resolved at runtime
-  (when action/transformation is executed) and not when loading the config
-
 # Testing
 
 Dotdrop is tested with the use of the [tests.sh](/tests.sh) script.
diff --git a/dotdrop/cfg_yaml.py b/dotdrop/cfg_yaml.py
index b0c9cd0..fc49647 100644
--- a/dotdrop/cfg_yaml.py
+++ b/dotdrop/cfg_yaml.py
@@ -89,47 +89,6 @@ class CfgYaml:
     lnk_link = LinkTypes.LINK.name.lower()
     lnk_children = LinkTypes.LINK_CHILDREN.name.lower()
 
-    # TODO
-    #
-    # "include" entries:
-    #   - import_actions
-    #   - import_configs
-    #   - import_variables
-    #   - profile's import
-    #   - profile's include
-    #
-    # variable precedence:
-    # 1) profile variable
-    # 2) "import_variables" variables
-    # 3) "import_configs" variables
-    # 4) other variables
-    #
-    # rules:
-    # - dynvariables are executed in their own config file
-    # - profile cannot include profiles defined above in the import tree
-    # - config files do not have access to variables
-    #   defined above in the import tree
-    #
-    # parse a config file
-    # - parse settings
-    # - parse variables
-    #   - interprete dynvariables
-    #   - template the include entries
-    # - parse profiles
-    # - parse dotfiles
-    # - parse other elements (actions, trans_r, trans_w)
-    # - parse and integrate included elements (see below)
-    #
-    # parse "include" entry
-    # - same as parse config file
-    # - add new entry to the top dict
-    #
-    # TODO
-    # - properly handle the included profile
-    # - document precedence in wiki
-    # - document parsing in CONTRIBUTING.md
-    #
-
     def __init__(self, path, profile=None, addprofiles=[], debug=False):
         """
         config parser