diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst index 41cc2dac..8d3f9de7 100644 --- a/docs/CONTRIBUTING.rst +++ b/docs/CONTRIBUTING.rst @@ -34,7 +34,7 @@ The key factor is that the first line of the commit message must follow this for .. code-block:: - type(scope): subject + type(scope): subject * E.g. ``docs(contributing): add commit message formatting instructions``. @@ -44,11 +44,11 @@ So based on the example above: .. - .. raw:: html + .. raw:: html -

Documentation

+

Documentation

- * **contributing:** add commit message formatting instructions + * **contributing:** add commit message formatting instructions * The ``type`` translates into a ``Documentation`` sub-heading. @@ -70,71 +70,73 @@ This formula applies some customisations to the defaults, as outlined in the tab based upon the `type `_ of the commit: .. list-table:: - :name: commit-type-vs-version-bump - :header-rows: 1 - :stub-columns: 0 - :widths: 1,2,3,1,1 - - * - Type - - Heading - - Description - - Bump (default) - - Bump (custom) - * - ``build`` - - Build System - - Changes related to the build system - - – - - - * - ``chore`` - - – - - Changes to the build process or auxiliary tools and libraries such as documentation generation - - – - - - * - ``ci`` - - Continuous Integration - - Changes to the continuous integration configuration - - – - - - * - ``docs`` - - Documentation - - Documentation only changes - - – - - 0.0.1 - * - ``feat`` - - Features - - A new feature - - 0.1.0 - - - * - ``fix`` - - Bug Fixes - - A bug fix - - 0.0.1 - - - * - ``perf`` - - Performance Improvements - - A code change that improves performance - - 0.0.1 - - - * - ``refactor`` - - Code Refactoring - - A code change that neither fixes a bug nor adds a feature - - – - - 0.0.1 - * - ``revert`` - - Reverts - - A commit used to revert a previous commit - - – - - 0.0.1 - * - ``style`` - - Styles - - Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.) - - – - - 0.0.1 - * - ``test`` - - Tests - - Adding missing or correcting existing tests - - – - - 0.0.1 + :name: commit-type-vs-version-bump + :header-rows: 1 + :stub-columns: 0 + :widths: 1,2,3,1,1 + + * - Type + - Heading + - Description + - Bump (default) + - Bump (custom) + * - ``build`` + - Build System + - Changes related to the build system + - – + - + * - ``chore`` + - – + - Changes to the build process or auxiliary tools and libraries such as + documentation generation + - – + - + * - ``ci`` + - Continuous Integration + - Changes to the continuous integration configuration + - – + - + * - ``docs`` + - Documentation + - Documentation only changes + - – + - 0.0.1 + * - ``feat`` + - Features + - A new feature + - 0.1.0 + - + * - ``fix`` + - Bug Fixes + - A bug fix + - 0.0.1 + - + * - ``perf`` + - Performance Improvements + - A code change that improves performance + - 0.0.1 + - + * - ``refactor`` + - Code Refactoring + - A code change that neither fixes a bug nor adds a feature + - – + - 0.0.1 + * - ``revert`` + - Reverts + - A commit used to revert a previous commit + - – + - 0.0.1 + * - ``style`` + - Styles + - Changes that do not affect the meaning of the code (white-space, + formatting, missing semi-colons, etc.) + - – + - 0.0.1 + * - ``test`` + - Tests + - Adding missing or correcting existing tests + - – + - 0.0.1 Use ``BREAKING CHANGE`` to trigger a ``major`` version change ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -149,11 +151,11 @@ An example of that: .. code-block:: git - ... + ... - BREAKING CHANGE: With the removal of all of the `.sls` files under - `template/package/`, this formula no longer supports the installation of - packages. + BREAKING CHANGE: With the removal of all of the `.sls` files under + `template package`, this formula no longer supports the installation of + packages. Documentation ------------- @@ -175,11 +177,11 @@ Adding a new page Adding a new page involves two steps: #. Use the - :ref:`saltstack_formulas_rst_page_template ` + :ref:`provided page template ` to create a new page. #. Add the page name under the ``toctree`` list in ``index.rst``. - #. Do not just append it to the list. + a. Do not just append it to the list. #. Select the best place where it fits within the overall documentation. SaltStack-Formulas' RST page template @@ -195,50 +197,50 @@ we are using for some of the pages of this documentation. .. code-block:: rst - .. _template: + .. _template: - [Page title] - ============ + [Page title] + ============ - [Introductory paragraph(s)] + [Introductory paragraph] - .. contents:: **Table of Contents** + .. contents:: **Table of Contents** - [Heading 2] - ----------- + [Heading 2] + ----------- - [Heading 3] - ^^^^^^^^^^^ + [Heading 3] + ^^^^^^^^^^^ - [Heading 4] - ~~~~~~~~~~~ + [Heading 4] + ~~~~~~~~~~~ - [Heading 5] - """"""""""" + [Heading 5] + """"""""""" - [Heading 6] - ########### + [Heading 6] + ########### #. The first line is an anchor that can be used to link back to (the top of) this file. - #. Change this to be the lowercase version of the file name. + a. Change this to be the lowercase version of the file name. #. Do not include the ``.rst`` file extension. #. Use hyphens (``-``) instead of spaces or non-letter characters. -#. Change the ``[Page title]`` accordingly, matching the same number of ``=`` - underneath. -#. Change the ``[Introductory paragraph(s)]`` to be a short summary of the page +#. Change the ``[Page title]`` accordingly, matching the same number of equals + signs (``=``) underneath. +#. Change the ``[Introductory paragraph]`` to be a short summary of the page content. Use no more than three paragraphs for this. #. Leave the ``..contents:: **Table of Contents**`` line as it is. #. Use the remaining headings as required to break up the page content. - #. You will rarely need to use beyond ``[Heading 4]``. + a. You will rarely need to use beyond ``[Heading 4]``. #. Again, no single heading should have more than about three paragraphs of - #. content before the next heading or sub-heading is used. + content before the next heading or sub-heading is used. Obviously, it is not necessary to follow the steps in the order above. -For example, it is usually easier to write the ``[Introductory paragraph(s)]`` +For example, it is usually easier to write the ``[Introductory paragraph]`` at the end. diff --git a/docs/README.rst b/docs/README.rst index 04306b92..6abbd4da 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -6,17 +6,17 @@ template-formula |img_travis| |docs| |img_sr| .. |img_travis| image:: https://travis-ci.com/saltstack-formulas/template-formula.svg?branch=master - :alt: Travis CI Build Status - :scale: 100% - :target: https://travis-ci.com/saltstack-formulas/template-formula + :alt: Travis CI Build Status + :scale: 100% + :target: https://travis-ci.com/saltstack-formulas/template-formula .. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest - :alt: Documentation Status - :scale: 100% - :target: https://template-formula.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + :scale: 100% + :target: https://template-formula.readthedocs.io/en/latest/?badge=latest .. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg - :alt: Semantic Release - :scale: 100% - :target: https://github.com/semantic-release/semantic-release + :alt: Semantic Release + :scale: 100% + :target: https://github.com/semantic-release/semantic-release A SaltStack formula that is empty. It has dummy content to help with a quick start on a new formula and it serves as a style guide. @@ -42,18 +42,18 @@ Contributing to this repo **Commit message formatting is significant!!** -Please see :ref:`contributing ` for more details. +Please see :ref:`How to contribute ` for more details. Available states ---------------- .. contents:: - :local: + :local: ``template`` ^^^^^^^^^^^^ -Meta-state (This is a state that includes other states) +*Meta-state (This is a state that includes other states)*. This installs the template package, manages the template configuration file and then @@ -79,7 +79,7 @@ via include list. ``template.clean`` ^^^^^^^^^^^^^^^^^^ -Meta-state (This is a state that includes other states) +*Meta-state (This is a state that includes other states)*. this state will undo everything performed in the ``template`` meta-state in reverse order, i.e. stops the service, @@ -94,12 +94,12 @@ This state will stop the template service and disable it at boot time. ``template.config.clean`` ^^^^^^^^^^^^^^^^^^^^^^^^^ -This state will remove the configuration of the template service and has a dependency on ``template.service.clean`` -via include list. +This state will remove the configuration of the template service and has a +dependency on ``template.service.clean`` via include list. ``template.package.clean`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ -This state will remove the template package and has a depency on ``template.config.clean`` -via include list. +This state will remove the template package and has a depency on +``template.config.clean`` via include list. diff --git a/docs/TOFS_pattern.rst b/docs/TOFS_pattern.rst index ebbd4a45..e7eeec0b 100644 --- a/docs/TOFS_pattern.rst +++ b/docs/TOFS_pattern.rst @@ -4,27 +4,27 @@ TOFS: A pattern for using SaltStack =================================== .. list-table:: - :name: tofs-authors - :header-rows: 1 - :stub-columns: 1 - :widths: 2,2,3,2 - - * - - - Person - - Contact - - Date - * - Authored by - - Roberto Moreda - - moreda@allenta.com - - 29/12/2014 - * - Modified by - - Daniel Dehennin - - daniel.dehennin@baby-gnu.org - - 07/02/2019 - * - Modified by - - Imran Iqbal - - https://github.com/myii - - 23/02/2019 + :name: tofs-authors + :header-rows: 1 + :stub-columns: 1 + :widths: 2,2,3,2 + + * - + - Person + - Contact + - Date + * - Authored by + - Roberto Moreda + - moreda@allenta.com + - 29/12/2014 + * - Modified by + - Daniel Dehennin + - daniel.dehennin@baby-gnu.org + - 07/02/2019 + * - Modified by + - Imran Iqbal + - https://github.com/myii + - 23/02/2019 All that follows is a proposal based on my experience with `SaltStack `_. The good thing of a piece of software like this is that you can "bend it" to suit your needs in many possible ways, and this is one of them. All the recommendations and thoughts are given "as it is" with no warranty of any type. @@ -33,13 +33,13 @@ All that follows is a proposal based on my experience with `SaltStack `_ is the list of directories used in sequence to find a file when a minion requires it: the first match is served to the minion. Those files could be `state files `_ or configuration templates, among others. +Among other functions, the *master* (or *salt-master*) serves files to the *minions* (or *salt-minions*). The `file_roots `_ is the list of directories used in sequence to find a file when a minion requires it: the first match is served to the minion. Those files could be `state files `_ or configuration templates, among others. Using SaltStack is a simple and effective way to implement configuration management, but even in a `non-multitenant `_ scenario, it is not a good idea to generally access some data (e.g. the database password in our `Zabbix `_ server configuration file or the private key of our `Nginx `_ TLS certificate). -To avoid this situation we can use the `pillar mechanism `_\ , which is designed to provide controlled access to data from the minions based on some selection rules. As pillar data could be easily integrated in the `Jinja `_ templates, it is a good mechanism to store values to be used in the final rendering of state files and templates. +To avoid this situation we can use the `pillar mechanism `_, which is designed to provide controlled access to data from the minions based on some selection rules. As pillar data could be easily integrated in the `Jinja `_ templates, it is a good mechanism to store values to be used in the final rendering of state files and templates. -There are a variety of approaches on the usage of pillar and templates as seen in the `saltstack-formulas `_\ ' repositories. `Some `_ `developments `_ stress the initial purpose of pillar data into a storage for most of the possible variables for a determined system configuration. This, in my opinion, is shifting too much load from the original template files approach. Adding up some `non-trivial Jinja `_ code as essential part of composing the state file definitely makes SaltStack state files (hence formulas) more difficult to read. The extreme of this approach is that we could end up with a new render mechanism, implemented in Jinja, storing everything needed in pillar data to compose configurations. Additionally, we are establishing a strong dependency with the Jinja renderer. +There are a variety of approaches on the usage of pillar and templates as seen in the `saltstack-formulas `_' repositories. `Some `_ `developments `_ stress the initial purpose of pillar data into a storage for most of the possible variables for a determined system configuration. This, in my opinion, is shifting too much load from the original template files approach. Adding up some `non-trivial Jinja `_ code as essential part of composing the state file definitely makes SaltStack state files (hence formulas) more difficult to read. The extreme of this approach is that we could end up with a new render mechanism, implemented in Jinja, storing everything needed in pillar data to compose configurations. Additionally, we are establishing a strong dependency with the Jinja renderer. In opposition to the *put the code in file_roots and the data in pillars* approach, there is the *pillar as a store for a set of key-values* approach. A full-blown configuration file abstracted in pillar and jinja is complicated to develop, understand and maintain. I think a better and simpler approach is to keep a configuration file templated using just a basic (non-extensive but extensible) set of pillar values. @@ -76,7 +76,7 @@ Let's work with the NTP example. A basic formula that follows the `design guidel etc/ ntp.conf.jinja -In order to use it, let's assume a `masterless configuration `_ and this relevant section of ``/etc/salt/minion``\ : +In order to use it, let's assume a `masterless configuration `_ and this relevant section of ``/etc/salt/minion``: .. code-block:: yaml @@ -91,7 +91,7 @@ In order to use it, let's assume a `masterless configuration - CONTRIBUTING - TOFS_pattern + README + CONTRIBUTING + TOFS_pattern