[DOC] update readme, change main.yml (fix #1)

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
 -------

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

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: