From dcd50fdbcfbf5c416bc927b5ce01eb34e6422c6a Mon Sep 17 00:00:00 2001
From: Jeremy Lecour <jlecour@evolix.fr>
Date: Fri, 13 Jan 2017 10:04:20 +0100
Subject: [PATCH] Switch to fenced code blocks

---
 CONVENTIONS.md | 119 ++++++++++++++++++++++++++++++-------------------
 1 file changed, 72 insertions(+), 47 deletions(-)

diff --git a/CONVENTIONS.md b/CONVENTIONS.md
index 93bea69..a9709e8 100644
--- a/CONVENTIONS.md
+++ b/CONVENTIONS.md
@@ -4,26 +4,29 @@
 
 We can use the `ansible-galaxy init` command to bootstrap a new role :
 
-    $ ansible-galaxy init foo
-    - foo was created successfully
-    $ tree foo
-    foo
-    ├── defaults
-    │   └── main.yml
-    ├── files
-    ├── handlers
-    │   └── main.yml
-    ├── meta
-    │   └── main.yml
-    ├── README.md
-    ├── tasks
-    │   └── main.yml
-    ├── templates
-    ├── tests
-    │   ├── inventory
-    │   └── test.yml
-    └── vars
-        └── main.yml
+```
+$ ansible-galaxy init foo
+- foo was created successfully
+
+$ tree foo
+foo
+├── defaults
+│   └── main.yml
+├── files
+├── handlers
+│   └── main.yml
+├── meta
+│   └── main.yml
+├── README.md
+├── tasks
+│   └── main.yml
+├── templates
+├── tests
+│   ├── inventory
+│   └── test.yml
+└── vars
+    └── main.yml
+```
 
 All `main.yml` file will be picked up by Ansible automatically, with respect to their own responsibility.
 
@@ -35,9 +38,12 @@ The main directory is `tasks`. It will contains tasks, either all in the `main.y
 
 `files` is the directory where we'll put files to copy on hosts. They will be copied "as-is". When a role has multiple logical groups of tasks, it's best to create a sub-directory for each group that needs files. The name of files in these directories doesn't have to be the same as the destination name. Example :
 
-    copy:
-      src: apt/jessie_backports_preferences
-      dest: /etc/apt/apt.conf.d/backports
+```
+copy:
+  src: apt/jessie_backports_preferences
+  dest: /etc/apt/apt.conf.d/backports
+```
+
 
 `templates` is the twin brother of `files`, but differs in that it contains files that can be pre-processed by the Jinja2 templating language. It can contain variables that will be extrapolated before copying the file to its destination.
 
@@ -59,19 +65,23 @@ We create roles (instead of a plain tasks files) when it makes sense as a whole,
 
 It's possible to use a compact (Ansible specific) syntax,
 
-    - name: Add evomaintenance trap for '{{ user.name }}'
-      lineinfile: state=present dest='/home/{{ user.name }}/.profile' insertafter=EOF line='trap "sudo /usr/share/scripts/evomaintenance.sh" 0'
-      when: evomaintenance_script.stat.exists
+```
+- name: Add evomaintenance trap for '{{ user.name }}'
+  lineinfile: state=present dest='/home/{{ user.name }}/.profile' insertafter=EOF line='trap "sudo /usr/share/scripts/evomaintenance.sh" 0'
+  when: evomaintenance_script.stat.exists
+```
 
 but we prefer the pure-YAML syntax
 
-    - name: Add evomaintenance trap for '{{ user.name }}'
-      lineinfile:
-        state: present
-        dest: '/home/{{ user.name }}/.profile'
-        insertafter: EOF
-        line: 'trap "sudo /usr/share/scripts/evomaintenance.sh" 0'
-      when: evomaintenance_script.stat.exists
+```
+- name: Add evomaintenance trap for '{{ user.name }}'
+  lineinfile:
+    state: present
+    dest: '/home/{{ user.name }}/.profile'
+    insertafter: EOF
+    line: 'trap "sudo /usr/share/scripts/evomaintenance.sh" 0'
+  when: evomaintenance_script.stat.exists
+```
 
 Here are some reasons :
 
@@ -86,6 +96,14 @@ Here are some reasons :
 
 When a role is using variables, they must be defined (for example in the `defaults/main.yml`) with a default value (possibly Null). That way, there will never be a "foo is undefined" situation.
 
+If a variable can't have a default value, it must be marked as [mandatory](http://docs.ansible.com/ansible/playbooks_filters.html#forcing-variables-to-be-defined). Example :
+
+```
+- name: Setting default timezone
+  lineinfile:
+    line: "{{ evolinux_system_timezone | mandatory }}"
+```
+
 ### progressive specificity
 
 In many roles, we use a *progressive specificity* pattern for some variables.
@@ -93,14 +111,18 @@ The most common is for "alert_email" ; we want to have a default email address w
 
 For the *evolinux-base* role we have those defaults :
 
-    general_alert_email: "root@localhost"
-    reboot_alert_email: Null
-    log2mail_alert_email: Null
-    raid_alert_email: Null
+```
+  general_alert_email: "root@localhost"
+  reboot_alert_email: Null
+  log2mail_alert_email: Null
+  raid_alert_email: Null
+```
 
 In the *log2mail* template, we set the email address like this :
 
-    mailto = {{ log2mail_alert_email or general_alert_email | mandatory }}
+```
+mailto = {{ log2mail_alert_email or general_alert_email | mandatory }}
+```
 
 If nothing is customized, the mail will be sent to root@localhost, if general_alert_email is changed, it will be used, but if log2mail_alert_email is set to a non-null value, it will have precedence.
 
@@ -142,18 +164,21 @@ We try not to alter configuration files managed by packages. It makes upgrading
 
 We usually put a `z-evolinux-defaults` with our core configuration. This file can be changed later via Ansible and must not be edited by hand. Example :
 
-    copy:
-      src: evolinux-defaults.cnf
-      dest: /etc/mysql/conf.d/z-evolinux-defaults.cnf
-      force: yes
-
+```
+copy:
+  src: evolinux-defaults.cnf
+  dest: /etc/mysql/conf.d/z-evolinux-defaults.cnf
+  force: yes
+```
 
 We also create a blank `zzz-evolinux-custom` file, with commented examples, to allow custom configuration that will never be reverted by Ansible. Example :
 
-    copy:
-      src: evolinux-custom.cnf
-      dest: /etc/mysql/conf.d/zzz-evolinux-custom.cnf
-      force: no
+```
+copy:
+  src: evolinux-custom.cnf
+  dest: /etc/mysql/conf.d/zzz-evolinux-custom.cnf
+  force: no
+```
 
 The source file or template shouldn't to be prefixed for ordering (eg. `z-` or `zzz-`). It's the task's responsibility to choose how destination files must be ordered.