summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorThomas Wiest <twiest@redhat.com>2015-06-24 11:28:57 -0400
committerThomas Wiest <twiest@redhat.com>2015-06-24 13:24:26 -0400
commit071880756c6862a8e45851735a19c3e9b33b4200 (patch)
tree71142d118ea347f6d604c0f2e2826844f0adcd99
parentb02c7b49602c446cddbcd5d6f763321bb8414131 (diff)
downloadopenshift-071880756c6862a8e45851735a19c3e9b33b4200.tar.gz
openshift-071880756c6862a8e45851735a19c3e9b33b4200.tar.bz2
openshift-071880756c6862a8e45851735a19c3e9b33b4200.tar.xz
openshift-071880756c6862a8e45851735a19c3e9b33b4200.zip
Added using Yaml syntax to best practices guide.
-rw-r--r--docs/best_practices_guide.adoc52
1 files changed, 52 insertions, 0 deletions
diff --git a/docs/best_practices_guide.adoc b/docs/best_practices_guide.adoc
index 1e96655e1..9208e99a3 100644
--- a/docs/best_practices_guide.adoc
+++ b/docs/best_practices_guide.adoc
@@ -125,6 +125,58 @@ YAML is a superset of JSON, which means that Ansible allows JSON syntax to be in
Every effort should be made to keep our Ansible YAML files in pure YAML.
+'''
+[cols="2v,v"]
+|===
+| **Rule**
+| Parameters to Ansible Modules SHOULD use the Yaml dictionary format when 3 or more parameters are being passed
+|===
+
+When a module has several parameters that are being passed in, it's hard to see exactly what value each parameter is getting. It is preferred to use the Ansible Yaml syntax to pass in parameters so that it's more clear what values are being passed for each paramemter.
+
+.Bad:
+[source,yaml]
+----
+- file: src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link
+----
+
+.Good:
+[source,yaml]
+----
+- file:
+ src: /file/to/link/to
+ dest: /path/to/symlink
+ owner: foo
+ group: foo
+ state: link
+----
+
+
+'''
+[cols="2v,v"]
+|===
+| **Rule**
+| Parameters to Ansible Modules SHOULD use the Yaml dictionary format when the line length exceeds 120 characters
+|===
+
+Lines that are long quickly become a wall of text that isn't easily parsable. It is preferred to use the Ansible Yaml syntax to pass in parameters so that it's more clear what values are being passed for each paramemter.
+
+.Bad:
+[source,yaml]
+----
+- get_url: url=http://example.com/path/file.conf dest=/etc/foo.conf sha256sum=b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
+----
+
+.Good:
+[source,yaml]
+----
+- get_url:
+ url: http://example.com/path/file.conf
+ dest: /etc/foo.conf
+ sha256sum: b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
+----
+
+
=== Defensive Programming
.Context