From 51309266b3ae3800f82b2be8fd57ede9d27aaba5 Mon Sep 17 00:00:00 2001 From: Thomas Wiest Date: Tue, 19 May 2015 09:57:41 -0400 Subject: Added style and best practices guides --- docs/style_guide.adoc | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/style_guide.adoc (limited to 'docs/style_guide.adoc') 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. -- cgit v1.2.3 From 437a88e4516d8c99211cbce535a25532bd3c5493 Mon Sep 17 00:00:00 2001 From: Thomas Wiest Date: Tue, 26 May 2015 10:15:31 -0400 Subject: Added concepts guide. --- docs/style_guide.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/style_guide.adoc') diff --git a/docs/style_guide.adoc b/docs/style_guide.adoc index 26a8c4636..714b56c70 100644 --- a/docs/style_guide.adoc +++ b/docs/style_guide.adoc @@ -1,7 +1,7 @@ // 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. -- cgit v1.2.3 From 1e1de9761184eb0732d4880bfb4188097530249f Mon Sep 17 00:00:00 2001 From: Thomas Wiest Date: Tue, 26 May 2015 16:40:46 -0400 Subject: removed references to 'we' --- docs/style_guide.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/style_guide.adoc') diff --git a/docs/style_guide.adoc b/docs/style_guide.adoc index 714b56c70..b4c99e1d9 100644 --- a/docs/style_guide.adoc +++ b/docs/style_guide.adoc @@ -13,7 +13,7 @@ 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. +Ansible global variables are defined as any variables outside of ansible roles. Examples include playbook variables, variables passed in on the cli, etc. ''' [cols="2v,v"] @@ -30,7 +30,7 @@ g_environment: someval ---- ==== Role Variables -We define Ansible role variables as variables contained in (or passed into) a role. +Ansible role variables are defined as variables contained in (or passed into) a role. ''' [cols="2v,v"] @@ -104,4 +104,4 @@ Even though both roles have the same prefix (mur), and even though both roles ha 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. +This is enough of a corner case that it is unlikely to happen. If it does, it will be addressed on a case by case basis. -- cgit v1.2.3