From 8fb156e73c10817ce3a4f43f6bf12e539482b7c7 Mon Sep 17 00:00:00 2001
From: L3D <l3d@c3woc.de>
Date: Mon, 2 Mar 2020 15:43:31 +0100
Subject: [PATCH] improve docs

---
 README.md         | 62 ++++++++++++++++++++++++++++++++++++++++++++++-
 defaults/main.yml |  1 +
 vars/main.yml     |  2 +-
 3 files changed, 63 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index c89705b..3715261 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,66 @@
 ============================
 Ansible role to install the Extra Packages for Enterprise Linux (EPEL) - Repository on RHEL and centos.
 
+### What do we do here?
++ First we read the variables you configured and our default values.
++ If enabled *(default to false)*, we do a simple version-check that will validate that you never run a older version of this role after you run this role before.
++ We validate that the GPG key of the EPEL repo for your distribution release is installed and match the fingerprint in the config.
++ We install the epel repo from a remote URL.
+
+### example useage of this role
+You can either use this role via ansible galaxy or by downloading this role manually.
+
+#### ansible galaxy: install this role
+```bash
+ansible-galaxy install do1jlr.epel
+```
+
+#### ansible-galaxy: example playbook
+```yml
+---
+- name: install epel release
+  hosts: srv01.example.com
+  roles:
+    - do1jlr.epel
+```
+
+#### manual download role
+```bash
+# download to your roles directory
+git clone https://github.com/roles-ansible/role_install-epel-release.git
+```
+
+#### manual example playbook
+```yaml
+---
+- name: Install epel release
+  hosts: srv02.example.com
+  tags:
+   - epel
+  vars:
+    submodules_versioncheck: true
+  roles:
+    - role_install-epel-release
+``` 
+
+### variables and configuration
+
+Here a our default values you can overwrite:
+```yaml
+# do we want a simple versionscheck? (true is recomended)
+submodules_versioncheck: false
+
+# epel repo
+epel_repo:
+  url: "https://dl.fedoraproject.org/pub/epel/epel-release-latest-{{ ansible_distribution_major_version }}.noarch.rpm"
+  gpg_key_url: "https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-{{ ansible_distribution_major_version }}"
+  gpg_key_path: "/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-{{ ansible_distribution_major_version }}"
+  fingerprint:
+    '6': "8C3B E96A F230 9184 DA5C 0DAE 3B49 DF2A 0608 B895"
+    '7': "91E9 7D7C 4A5E 96F1 7F3E 888F 6A2F AEA2 352C 64E5"
+    '8': "94E2 79EB 8D8F 25B2 1810 ADF1 21EA 45AB 2F86 D6A1"
+```
+
 ### Testing
 This role is tested with [these github-action](https://github.com/search?q=topic%3Acentos+topic%3Acheck-ansible+topic%3Agithub-actions+org%3Aroles-ansible&type=Repositories) tests for different versions of centos. Linting is tested via travis-ci.
 If you want to find out more about our tests, please have a look at the github marketplace.
@@ -26,9 +86,9 @@ WORK IN PROGRESS
 
 missing:
 - os detection (RHEL)
-- docs
 
 working:
+- docs
 - epel install on centos 7
 - github-actions
 - vars
diff --git a/defaults/main.yml b/defaults/main.yml
index b230bb4..b12c2d3 100644
--- a/defaults/main.yml
+++ b/defaults/main.yml
@@ -1,4 +1,5 @@
 ---
+# do we want a simple versionscheck? (true is recomended)
 submodules_versioncheck: false
 # epel repo
 epel_repo:
diff --git a/vars/main.yml b/vars/main.yml
index 66954c1..791f675 100644
--- a/vars/main.yml
+++ b/vars/main.yml
@@ -1,5 +1,5 @@
 ---
-playbook_version_number: 1025 # should be over ninethousand
+playbook_version_number: 1026 # should be over ninethousand
 playbook_version_path: 'role-epel_roles-ansible_github.com.version' 
 # epel repo
 _epel_repo: