From e43fc1b515fa87994228098e00632360ea5946b5 Mon Sep 17 00:00:00 2001 From: Thomas Wiest Date: Thu, 4 Jun 2015 10:08:06 -0400 Subject: Added YAML over JSON to best practices guide. --- docs/best_practices_guide.adoc | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/best_practices_guide.adoc b/docs/best_practices_guide.adoc index 2768059b3..841f6e72c 100644 --- a/docs/best_practices_guide.adoc +++ b/docs/best_practices_guide.adoc @@ -78,6 +78,27 @@ metadata[line] = results.pop() == Ansible +=== Yaml Files (Playbooks, Roles, Vars, etc) + +''' +[cols="2v,v"] +|=== +| **Rule** +| Ansible files SHOULD NOT use JSON (use pure YAML instead). +|=== + +YAML is a superset of JSON, which means that Ansible allows JSON syntax to be interspersed. Even though YAML (and by extension Ansible) allows for this, JSON SHOULD NOT be used. + +.Reasons: +* Ansible is able to give clearer error messages when the files are pure YAML +* YAML reads nicer (preference held by several team members) +* YAML makes for nicer diffs as YAML tends to be multi-line, whereas JSON tends to be more concise + +.Exceptions: +* Ansible static inventory files are INI files. To pass in variables for specific hosts, Ansible allows for these variables to be put inside of the static inventory files. These variables can be in JSON format, but can't be in YAML format. This is an acceptable use of JSON, as YAML is not allowed in this case. + +Every effort should be made to keep our Ansible YAML files in pure YAML. + === Defensive Programming .Context @@ -122,8 +143,6 @@ If an Ansible role requires certain variables to be set, it's best to check for ---- === Roles -.Context -* http://docs.ansible.com/playbooks_best_practices.html#directory-layout[Ansible Suggested Directory Layout] ''' [cols="2v,v"] @@ -132,6 +151,9 @@ If an Ansible role requires certain variables to be set, it's best to check for | The Ansible roles directory MUST maintain a flat structure. |=== +.Context +* http://docs.ansible.com/playbooks_best_practices.html#directory-layout[Ansible Suggested Directory Layout] + .The purpose of this rule is to: * Comply with the upstream best practices * Make it familiar for new contributors -- cgit v1.2.3