Merge pull request #243 from twiest/pr

Added style and best practices guides

1 files changed, 107 insertions, 0 deletions

diff --git a/docs/style_guide.adoc b/docs/style_guide.adoc
new file mode 100644
index 000000000..26a8c4636
--- /dev/null
+++ b/docs/style_guide.adoc
@@ -0,0 +1,107 @@
+// vim: ft=asciidoc
+
+= Openshift-Ansible Style Guide
+-----------------------------
+The purpose of this guide is to describe the preferred coding conventions used in this repository (both in ansible and python).
+
+It is important to note that this repository may not currently comply with all style guide rules, but our intention is that it will.
+
+All new pull requests created against this repository MUST comply with this guide.
+
+This style guide complies with https://www.ietf.org/rfc/rfc2119.txt[RFC2119].
+
+== Ansible Variable Naming
+
+=== Global Variables
+We define Ansible global variables as any variables outside of ansible roles. Examples include playbook variables, variables passed in on the cli, etc.
+
+'''
+[cols="2v,v"]
+|===
+| **Rule**
+| Global variables MUST have a prefix of g_
+|===
+
+
+Example:
+[source]
+----
+g_environment: someval
+----
+
+==== Role Variables
+We define Ansible role variables as variables contained in (or passed into) a role.
+
+'''
+[cols="2v,v"]
+|===
+| **Rule**
+| Role variables MUST have a prefix of atleast 3 characters. See below for specific naming rules.
+|===
+
+===== Role with 3 (or more) words in the name
+
+Take the first letter of each of the words.
+
+.3 word example:
+* Role name: made_up_role
+* Prefix: mur
+[source]
+----
+mur_var1: value_one
+----
+
+.4 word example:
+* Role name: totally_made_up_role
+* Prefix: tmur
+[source]
+----
+tmur_var1: value_one
+----
+
+
+
+===== Role with 2 (or less) words in the name
+
+Make up a prefix that makes sense.
+
+.1 word example:
+* Role name: ansible
+* Prefix: ans
+[source]
+----
+ans_var1: value_one
+----
+
+.2 word example:
+* Role name: ansible_tower
+* Prefix: tow
+[source]
+----
+tow_var1: value_one
+----
+
+
+===== Role name prefix conflicts
+If two role names contain words that start with the same letters, it will seem like their prefixes would conflict.
+
+Role variables are confined to the roles themselves, so this is actually only a problem if one of the roles depends on the other role (or uses includes into the other role).
+
+.Same prefix example:
+* First Role Name: made_up_role
+* First Role Prefix: mur
+* Second Role Name: my_uber_role
+* Second Role Prefix: mur
+[source]
+----
+- hosts: localhost
+  roles:
+  - { role: made_up_role, mur_var1: val1 }
+  - { role: my_uber_role, mur_var1: val2 }
+----
+
+Even though both roles have the same prefix (mur), and even though both roles have a variable named mur_var1, these two variables never exist outside of their respective roles. This means that this is not a problem.
+
+This would only be a problem if my_uber_role depended on made_up_role, or vice versa. Or if either of these two roles included things from the other.
+
+We think this is enough of a corner case that it is unlikely to happen. If it does, we will address it on a case by case basis.