docs/README.rst

   1 .. _readme:
   2
   3 TEMPLATE-formula
   4 ================
   5
   6 |img_travis| |img_sr|
   7
   8 .. |img_travis| image:: https://travis-ci.com/saltstack-formulas/TEMPLATE-formula.svg?branch=master
   9    :alt: Travis CI Build Status
  10    :scale: 100%
  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
  14    :scale: 100%
  15    :target: https://github.com/semantic-release/semantic-release
  16
  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.
  19
  20 .. contents:: **Table of Contents**
  21
  22 General notes
  23 -------------
  24
  25 See the full `SaltStack Formulas installation and usage instructions
  26 <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
  27
  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>`_.
  30
  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/>`_.
  33
  34 See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
  35
  36 If you need (non-default) configuration, please pay attention to the ``pillar.example`` file and/or `Special notes`_ section.
  37
  38 Contributing to this repo
  39 -------------------------
  40
  41 **Commit message formatting is significant!!**
  42
  43 Please see `How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>`_ for more details.
  44
  45 Special notes
  46 -------------
  47
  48 .. <REMOVEME
  49
  50 Using this template
  51 ^^^^^^^^^^^^^^^^^^^
  52
  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.
  54
  55 In the rest of this example we'll use ``example`` as the ``<formula theme>``.
  56
  57 Follow these steps to complete the conversion from ``template-formula`` to ``example-formula``. ::
  58
  59   $ git clone git@github.com:YOUR-USERNAME/example-formula.git
  60   $ cd example-formula/
  61   $ bin/convert-formula.sh example
  62   $ git push --force
  63
  64 Alternatively, it's possible to clone ``template-formula`` into a new repository and perform the conversion there. For example::
  65
  66   $ git clone https://github.com/saltstack-formulas/template-formula example-formula
  67   $ cd example-formula/
  68   $ bin/convert-formula.sh example
  69
  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.
  71
  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.
  73
  74 .. REMOVEME>
  75
  76 Available states
  77 ----------------
  78
  79 .. contents::
  80    :local:
  81
  82 ``TEMPLATE``
  83 ^^^^^^^^^^^^
  84
  85 *Meta-state (This is a state that includes other states)*.
  86
  87 This installs the TEMPLATE package,
  88 manages the TEMPLATE configuration file and then
  89 starts the associated TEMPLATE service.
  90
  91 ``TEMPLATE.package``
  92 ^^^^^^^^^^^^^^^^^^^^
  93
  94 This state will install the TEMPLATE package only.
  95
  96 ``TEMPLATE.config``
  97 ^^^^^^^^^^^^^^^^^^^
  98
  99 This state will configure the TEMPLATE service and has a dependency on ``TEMPLATE.install``
 100 via include list.
 101
 102 ``TEMPLATE.service``
 103 ^^^^^^^^^^^^^^^^^^^^
 104
 105 This state will start the TEMPLATE service and has a dependency on ``TEMPLATE.config``
 106 via include list.
 107
 108 ``TEMPLATE.clean``
 109 ^^^^^^^^^^^^^^^^^^
 110
 111 *Meta-state (This is a state that includes other states)*.
 112
 113 this state will undo everything performed in the ``TEMPLATE`` meta-state in reverse order, i.e.
 114 stops the service,
 115 removes the configuration file and
 116 then uninstalls the package.
 117
 118 ``TEMPLATE.service.clean``
 119 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 120
 121 This state will stop the TEMPLATE service and disable it at boot time.
 122
 123 ``TEMPLATE.config.clean``
 124 ^^^^^^^^^^^^^^^^^^^^^^^^^
 125
 126 This state will remove the configuration of the TEMPLATE service and has a
 127 dependency on ``TEMPLATE.service.clean`` via include list.
 128
 129 ``TEMPLATE.package.clean``
 130 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 131
 132 This state will remove the TEMPLATE package and has a depency on
 133 ``TEMPLATE.config.clean`` via include list.
 134
 135 ``TEMPLATE.subcomponent``
 136 ^^^^^^^^^^^^^^^^^^^^^^^^^
 137
 138 *Meta-state (This is a state that includes other states)*.
 139
 140 This state installs a subcomponent configuration file before
 141 configuring and starting the TEMPLATE service.
 142
 143 ``TEMPLATE.subcomponent.config``
 144 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 145
 146 This state will configure the TEMPLATE subcomponent and has a
 147 dependency on ``TEMPLATE.config`` via include list.
 148
 149 ``TEMPLATE.subcomponent.config.clean``
 150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 151
 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``
 155 requisite.
 156
 157 Testing
 158 -------
 159
 160 Linux testing is done with ``kitchen-salt``.
 161
 162 Requirements
 163 ^^^^^^^^^^^^
 164
 165 * Ruby
 166 * Docker
 167
 168 .. code-block:: bash
 169
 170    $ gem install bundler
 171    $ bundle install
 172    $ bin/kitchen test [platform]
 173
 174 Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
 175 e.g. ``debian-9-2019-2-py3``.
 176
 177 ``bin/kitchen converge``
 178 ^^^^^^^^^^^^^^^^^^^^^^^^
 179
 180 Creates the docker instance and runs the ``TEMPLATE`` main state, ready for testing.
 181
 182 ``bin/kitchen verify``
 183 ^^^^^^^^^^^^^^^^^^^^^^
 184
 185 Runs the ``inspec`` tests on the actual instance.
 186
 187 ``bin/kitchen destroy``
 188 ^^^^^^^^^^^^^^^^^^^^^^^
 189
 190 Removes the docker instance.
 191
 192 ``bin/kitchen test``
 193 ^^^^^^^^^^^^^^^^^^^^
 194
 195 Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
 196
 197 ``bin/kitchen login``
 198 ^^^^^^^^^^^^^^^^^^^^^
 199
 200 Gives you SSH access to the instance for manual testing.
 201