8 .. |img_travis| image:: https://travis-ci.com/saltstack-formulas/TEMPLATE-formula.svg?branch=master
9 :alt: Travis CI Build Status
11 :target: https://travis-ci.com/saltstack-formulas/TEMPLATE-formula
12 .. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
13 :alt: Semantic Release
15 :target: https://github.com/semantic-release/semantic-release
17 A SaltStack formula that is empty. It has dummy content to help with a quick
18 start on a new formula and it serves as a style guide.
20 .. contents:: **Table of Contents**
25 See the full `SaltStack Formulas installation and usage instructions
26 <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
28 If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
29 <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
31 If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
32 which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
34 See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
36 If you need (non-default) configuration, please pay attention to the ``pillar.example`` file and/or `Special notes`_ section.
38 Contributing to this repo
39 -------------------------
41 **Commit message formatting is significant!!**
43 Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.
53 The easiest way to use this template formula as a base for a new formula is to use GitHub's **Use this template** button to create a new repository. For consistency with the rest of the formula ecosystem, name your formula repository following the pattern ``<formula theme>-formula``, where ``<formula theme>`` consists of lower-case alphabetic characters and numbers.
55 In the rest of this example we'll use ``example`` as the ``<formula theme>``.
57 Follow these steps to complete the conversion from ``template-formula`` to ``example-formula``. ::
59 $ git clone git@github.com:YOUR-USERNAME/example-formula.git
61 $ bin/convert-formula.sh example
64 Alternatively, it's possible to clone ``template-formula`` into a new repository and perform the conversion there. For example::
66 $ git clone https://github.com/saltstack-formulas/template-formula example-formula
68 $ bin/convert-formula.sh example
70 To take advantage of `semantic-release <https://github.com/semantic-release/semantic-release>`_ for automated changelog generation and release tagging, you will need a GitHub `Personal Access Token <https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line>`_ with at least the **public_repo** scope.
72 In the Travis repository settings for your new repository, create an `environment variable <https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings>`_ named ``GH_TOKEN`` with the personal access token as value, restricted to the ``master`` branch for security.
85 *Meta-state (This is a state that includes other states)*.
87 This installs the TEMPLATE package,
88 manages the TEMPLATE configuration file and then
89 starts the associated TEMPLATE service.
94 This state will install the TEMPLATE package only.
99 This state will configure the TEMPLATE service and has a dependency on ``TEMPLATE.install``
105 This state will start the TEMPLATE service and has a dependency on ``TEMPLATE.config``
111 *Meta-state (This is a state that includes other states)*.
113 this state will undo everything performed in the ``TEMPLATE`` meta-state in reverse order, i.e.
115 removes the configuration file and
116 then uninstalls the package.
118 ``TEMPLATE.service.clean``
119 ^^^^^^^^^^^^^^^^^^^^^^^^^^
121 This state will stop the TEMPLATE service and disable it at boot time.
123 ``TEMPLATE.config.clean``
124 ^^^^^^^^^^^^^^^^^^^^^^^^^
126 This state will remove the configuration of the TEMPLATE service and has a
127 dependency on ``TEMPLATE.service.clean`` via include list.
129 ``TEMPLATE.package.clean``
130 ^^^^^^^^^^^^^^^^^^^^^^^^^^
132 This state will remove the TEMPLATE package and has a depency on
133 ``TEMPLATE.config.clean`` via include list.
135 ``TEMPLATE.subcomponent``
136 ^^^^^^^^^^^^^^^^^^^^^^^^^
138 *Meta-state (This is a state that includes other states)*.
140 This state installs a subcomponent configuration file before
141 configuring and starting the TEMPLATE service.
143 ``TEMPLATE.subcomponent.config``
144 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
146 This state will configure the TEMPLATE subcomponent and has a
147 dependency on ``TEMPLATE.config`` via include list.
149 ``TEMPLATE.subcomponent.config.clean``
150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
152 This state will remove the configuration of the TEMPLATE subcomponent
153 and reload the TEMPLATE service by a dependency on
154 ``TEMPLATE.service.running`` via include list and ``watch_in``
160 Linux testing is done with ``kitchen-salt``.
170 $ gem install bundler
172 $ bin/kitchen test [platform]
174 Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
175 e.g. ``debian-9-2019-2-py3``.
177 ``bin/kitchen converge``
178 ^^^^^^^^^^^^^^^^^^^^^^^^
180 Creates the docker instance and runs the ``TEMPLATE`` main state, ready for testing.
182 ``bin/kitchen verify``
183 ^^^^^^^^^^^^^^^^^^^^^^
185 Runs the ``inspec`` tests on the actual instance.
187 ``bin/kitchen destroy``
188 ^^^^^^^^^^^^^^^^^^^^^^^
190 Removes the docker instance.
195 Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
197 ``bin/kitchen login``
198 ^^^^^^^^^^^^^^^^^^^^^
200 Gives you SSH access to the instance for manual testing.