From 34a210905160add61eb03d5ad8787bedb39c0fa8 Mon Sep 17 00:00:00 2001
From: Jannik Beyerstedt <code@jannikbeyerstedt.de>
Date: Sat, 12 Oct 2019 13:09:27 +0200
Subject: [PATCH] [DOC] update readme, change main.yml (fix #1)

---
 README.md        | 52 ++++++++++++++++++++++++++++++++++++++++++------
 tasks/main.yml   | 22 ++++++++++++++------
 tasks/update.yml |  3 ---
 3 files changed, 62 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 3bbfccb..e9d40e8 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
 Common
 =========
 
-Common user settings and tools.
+Common user settings and tools used by Jannik Beyerstedt.
+This role is compatible with Debian based systems and macOS.
 
 
 Requirements
@@ -13,7 +14,10 @@ none
 Role Variables
 --------------
 
-TODO: set override_os_family in inventory for exotic OS like Mendel on Coral Board, which returns "Mendel GNU/Linux" but is a Debian derivative and uses apt.
+This role uses the apt package manager on Debian based hosts.
+But for some operating systems the `ansible_os_family` variable is not set to "Debian" by the fact gathering even if it is Debian based (like Mendel GNU/Linux on the Google Coral Dev Board).
+
+- `override_os_family`: Set to "Debian" in the host inventory, if `ansible_os_family` is not set correctly
 
 
 Dependencies
@@ -21,14 +25,50 @@ Dependencies
 
 none
 
+
 Example Playbook
 ----------------
 
-Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
+You can simply run the whole role:
+```yml
+- name: Basic User Shell Setup
+  hosts: all
+  strategy: free
+  tasks:
+  - name: Basics - Update first
+    import_role:
+      name: common
+      tasks_from: update
+  - name: Basics - Install essential tools
+    import_role:
+      name: common
+      tasks_from: essentials
+  - name: Basics - Install more tools
+    import_role:
+      name: common
+      tasks_from: tools
+
+  - name: Basics - Setup user shell
+    import_role:
+      name: common
+      tasks_from: usersetup
+  - name: Basics - Install dotfiles
+    import_role:
+      name: common
+      tasks_from: usersettings
+```
+
+Or call the different tasks individually:
+```yml
+- name: Basic User Shell Setup
+  hosts: all
+  strategy: free
+  tasks:
+  - name: Basics - Update first
+    roles:
+      - common
+```
 
-    - hosts: servers
-      roles:
-         - { role: username.rolename, x: 42 }
 
 License
 -------
diff --git a/tasks/main.yml b/tasks/main.yml
index cea198d..93c30f1 100644
--- a/tasks/main.yml
+++ b/tasks/main.yml
@@ -1,20 +1,30 @@
 ---
 # Common setup tasks for all nodes (universial)
-# ATTENTION: This is just the maintenance version of the Common role. Run all
-# tasks during setup in this order:
-# - essentials
-# - tools
-# - usersetup
-# - usersettings
+# Usage:
+# - Run this whole role for setup
+# - You will do nothing wrong, if all steps are executed during periodocal maintenance
+# - Maintenance can be faster, if some steps are left out:
+#   - Some tasks are only needed for setup
+#   - Some can be run periodically
+#   - Some must run periodically
 
 - name: Install updates
   import_tasks: update.yml
 
+
+# if role has not changed, this will not be needed when just installing updates
 - name: Install essential tools
   import_tasks: essentials.yml
 
+# if role has not changed, this will not be needed when just installing updates
 - name: Install more tools
   import_tasks: tools.yml
 
+
+# this will just run once, because of a lock-file
+- name: Basics - Setup user shell
+  import_tasks: usersetup.yml
+
+# run this for every maintenance/ update cycle
 - name: Apply user settings
   import_tasks: usersettings.yml
diff --git a/tasks/update.yml b/tasks/update.yml
index 38f3331..6d6e77e 100644
--- a/tasks/update.yml
+++ b/tasks/update.yml
@@ -1,9 +1,6 @@
 ---
 # Common/Update: Install All Updates
 
-- debug:
-    msg: OS Family {{ override_os_family }} -> {{ (override_os_family is defined) | ternary(override_os_family,ansible_os_family) }}
-
 - name: update - Update and upgrade all packages
   include_tasks: "{{ item }}"
   with_first_found: