Merge pull request #2 from myii/chore/standardise-structure

feat(semantic-release): implement for this formula

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,54 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: 'bug'
+assignees: ''
+
+---
+
+<!--
+Notes:
+1. Only post _bug reports_ here.
+2. Use the appropriate template for _feature requests_.
+3. Please direct questions to the [`#formulas` channel on Slack](https://saltstackcommunity.slack.com/messages/C7LG8SV54/), which is bridged to `#saltstack-formulas` on Freenode.
+-->
+
+#### Describe the bug
+<!-- A clear and concise description of what the bug is. -->
+
+
+
+#### Setup
+<!-- Provide links to the SLS files and/or relevant configs (be sure to remove sensitive info). -->
+
+
+
+#### Steps to reproduce the bug
+<!-- Include debug logs if possible and relevant, e.g. using `salt-minion -l debug`. -->
+<!-- Alternatively, linking to Kitchen debug logs is useful, e.g. via. Travis CI. -->
+<!-- Most useful is providing a failing InSpec test, which can be used to verify any proposed fix. -->
+
+
+
+#### Expected behaviour
+<!-- A clear and concise description of what you expected to happen. -->
+
+
+
+#### Versions report
+<!-- Provided by running `salt --versions-report`. Please also mention any differences in master/minion versions. -->
+
+
+
+#### Additional context
+<!-- Add any other context about the problem here. -->
+
+
+
+---
+
+#### Optional: How can this template be improved?
+<!-- Feel free to suggest how this template can be improved. -->
+
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,42 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: '[FEATURE] '
+labels: 'enhancement'
+assignees: ''
+
+---
+
+<!--
+Notes:
+1. Only post _feature requests_ here.
+2. Use the appropriate template for _bug reports_.
+3. Please direct questions to the [`#formulas` channel on Slack](https://saltstackcommunity.slack.com/messages/C7LG8SV54/), which is bridged to `#saltstack-formulas` on Freenode.
+-->
+
+#### Is your feature request related to a problem?
+<!-- A clear and concise description of what the problem is. -->
+
+
+
+#### Describe the solution you'd like
+<!-- A clear and concise description of what you want to happen. -->
+
+
+
+#### Describe alternatives you've considered
+<!-- Describe any alternative solutions or features you've considered. -->
+
+
+
+#### Additional context
+<!-- Add any other context about the feature request here. -->
+
+
+
+---
+
+#### Optional: How can this template be improved?
+<!-- Feel free to suggest how this template can be improved. -->
+
+

.travis.yml

@@ -1,16 +1,16 @@
 # -*- coding: utf-8 -*-
 # vim: ft=yaml
 ---
+dist: bionic
 stages:
   - test
-  - commitlint
+  - lint
   - name: release
     if: branch = master AND type != pull_request
 
 sudo: required
 cache: bundler
 language: ruby
-dist: xenial
 
 services:
   - docker
@@ -25,40 +25,49 @@ env:
     # - INSTANCE: default-fedora-30-develop-py3
     # - INSTANCE: default-opensuse-leap-15-develop-py3
     # - INSTANCE: default-amazonlinux-2-develop-py2
+    # - INSTANCE: default-arch-base-latest-develop-py2
     # - INSTANCE: default-debian-9-2019-2-py3
     - INSTANCE: default-ubuntu-1804-2019-2-py3
-    # - INSTANCE: default-centos-7-2019-2-py3
-    # - INSTANCE: default-fedora-30-2019-2-py3
+    - INSTANCE: default-centos-7-2019-2-py3
+    - INSTANCE: default-fedora-30-2019-2-py3
     # - INSTANCE: default-opensuse-leap-15-2019-2-py3
-    - INSTANCE: default-amazonlinux-2-2019-2-py2
+    # - INSTANCE: default-amazonlinux-2-2019-2-py2
+    # - INSTANCE: default-arch-base-latest-2019-2-py2
     # - INSTANCE: default-debian-9-2018-3-py2
     # - INSTANCE: default-ubuntu-1604-2018-3-py2
     # - INSTANCE: default-centos-7-2018-3-py2
-    - INSTANCE: default-fedora-29-2018-3-py2
+    # - INSTANCE: default-fedora-29-2018-3-py2
     - INSTANCE: default-opensuse-leap-15-2018-3-py2
     # - INSTANCE: default-amazonlinux-2-2018-3-py2
+    # - INSTANCE: default-arch-base-latest-2018-3-py2
     # - INSTANCE: default-debian-8-2017-7-py2
-    # - INSTANCE: default-ubuntu-1604-2017-7-py2
-    - INSTANCE: centos6-centos-6-2017-7-py2
+    - INSTANCE: default-ubuntu-1604-2017-7-py2
+    # - INSTANCE: default-centos-6-2017-7-py2
     # - INSTANCE: default-fedora-29-2017-7-py2
     # - INSTANCE: default-opensuse-leap-15-2017-7-py2
     # - INSTANCE: default-amazonlinux-2-2017-7-py2
+    # - INSTANCE: default-arch-base-latest-2017-7-py2
 
 script:
   - bin/kitchen verify ${INSTANCE}
 
 jobs:
   include:
-    # Define the commitlint stage
-    - stage: commitlint
+    # Define the `lint` stage (runs `yamllint` and `commitlint`)
+    - stage: lint
       language: node_js
       node_js: lts/*
       before_install: skip
       script:
+        # Install and run `yamllint`
+        # Need at least `v1.17.0` for the `yaml-files` setting
+        - pip install --user yamllint>=1.17.0
+        - yamllint -s .
+        # Install and run `commitlint`
         - npm install @commitlint/config-conventional -D
         - npm install @commitlint/travis-cli -D
         - commitlint-travis
-    # Define the release stage that runs semantic-release
+    # Define the release stage that runs `semantic-release`
     - stage: release
       language: node_js
       node_js: lts/*

.yamllint

@@ -6,10 +6,24 @@ extends: default
 
 # Files to ignore completely
 # 1. All YAML files under directory `node_modules/`, introduced during the Travis run
+# 2. Any SLS files under directory `test/`, which are actually state files
 ignore: |
   node_modules/
+  test/**/states/**/*.sls
+
+yaml-files:
+  # Default settings
+  - '*.yaml'
+  - '*.yml'
+  - .yamllint
+  # SaltStack Formulas additional settings
+  - '*.example'
+  - test/**/*.sls
 
 rules:
+  empty-values:
+    forbid-in-block-mappings: true
+    forbid-in-flow-mappings: true
   line-length:
     # Increase from default of `80`
     # Based on https://github.com/PyCQA/flake8-bugbear#opinionated-warnings (`B950`)

docs/TOFS_pattern.rst

@@ -444,3 +444,75 @@ Resulting in:
 Note: This does *not* override the default value.
 Rather, the value from the pillar/config is prepended to the default.
 
+Using sub-directories for ``components``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your formula is composed of several components, you may prefer to provides files under sub-directories, like in the `systemd-formula <https://github.com/saltstack-formulas/systemd-formula>`_.
+
+.. code-block::
+
+   /srv/saltstack/systemd-formula/
+     systemd/
+       init.sls
+       libtofs.jinja
+       map.jinja
+       networkd/
+         init.sls
+         files/
+           default/
+             network/
+               99-default.link
+       resolved/
+         init.sls
+         files/
+           default/
+             resolved.conf
+       timesyncd/
+         init.sls
+         files/
+           Arch/
+             resolved.conf
+           Debian/
+             resolved.conf
+           default/
+             resolved.conf
+           Ubuntu/
+             resolved.conf
+
+For example, the following ``formula.component.config`` SLS:
+
+.. code-block:: sls
+
+   {%- from "formula/libtofs.jinja" import files_switch with context %}
+
+   formula configuration file:
+     file.managed:
+       - name: /etc/formula.conf
+       - user: root
+       - group: root
+       - mode: 644
+       - template: jinja
+       - source: {{ files_switch(['formula.conf'],
+                                 lookup='formula',
+                                 use_subpath=True
+                    )
+                 }}
+
+will be rendered on a ``Debian`` minion named ``salt-formula.ci.local`` as:
+
+.. code-block:: sls
+
+   formula configuration file:
+     file.managed:
+       - name: /etc/formula.conf
+       - user: root
+       - group: root
+       - mode: 644
+       - template: jinja
+       - source:
+         - salt://formula/component/files/salt-formula.ci.local/formula.conf
+         - salt://formula/component/files/Debian/formula.conf
+         - salt://formula/component/files/default/formula.conf
+         - salt://formula/files/salt-formula.ci.local/formula.conf
+         - salt://formula/files/Debian/formula.conf
+         - salt://formula/files/default/formula.conf