chore: implement an automated changelog and semantic versioning

.travis.yml

@@ -1,3 +1,9 @@
+stages:
+  - test
+  - commitlint
+  - name: release
+    if: branch = master AND type != pull_request
+
 sudo: required
 cache: bundler
 language: ruby
@@ -9,6 +15,8 @@ before_install:
   - gem install bundler
   - bundle install
 
+# Make sure the instances listed below match up with
+# the `platforms` defined in `kitchen.yml`
 env:
   matrix:
     - INSTANCE: v2019-2-py3-debian-9
@@ -28,3 +36,37 @@ env:
 
 script:
   - bundle exec kitchen verify ${INSTANCE}
+
+jobs:
+  include:
+    # Define the commitlint stage
+    - stage: commitlint
+      language: node_js
+      node_js: lts/*
+      before_install: skip
+      script:
+        - npm install @commitlint/config-conventional -D
+        - npm install @commitlint/travis-cli -D
+        - commitlint-travis
+    # Define the release stage that runs semantic-release
+    - stage: release
+      language: node_js
+      node_js: lts/*
+      before_install: skip
+      script:
+        # Update `AUTHORS.md`
+        - export MAINTAINER_TOKEN=${GH_TOKEN}
+        - go get github.com/myii/maintainer
+        - maintainer contributor
+
+        # Install all dependencies required for `semantic-release`
+        - npm install @semantic-release/changelog@3 -D
+        - npm install @semantic-release/exec@3 -D
+        - npm install @semantic-release/git@7 -D
+      deploy:
+        provider: script
+        skip_cleanup: true
+        script:
+          # Run `semantic-release`
+          - npx semantic-release@15
+

commitlint.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+    extends: ['@commitlint/config-conventional'],
+};

docs/CONTRIBUTING.rst

@@ -0,0 +1,246 @@
+.. _contributing:
+
+How to contribute
+=================
+
+This document will eventually outline all aspects of guidance to make your contributing experience a fruitful and enjoyable one.
+What it already contains is information about *commit message formatting* and how that directly affects the numerous automated processes that are used for this repo.
+It also covers how to contribute to this *formula's documentation*.
+
+.. contents:: **Table of Contents**
+
+Overview
+--------
+
+Submitting a pull request is more than just code!
+To achieve a quality product, the *tests* and *documentation* need to be updated as well.
+An excellent pull request will include these in the changes, wherever relevant.
+
+Commit message formatting
+-------------------------
+
+Since every type of change requires making Git commits,
+we will start by covering the importance of ensuring that all of your commit
+messages are in the correct format.
+
+Automation of multiple processes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This formula uses `semantic-release <https://github.com/semantic-release/semantic-release>`_ for automating numerous processes such as bumping the version number appropriately, creating new tags/releases and updating the changelog.
+The entire process relies on the structure of commit messages to determine the version bump, which is then used for the rest of the automation.
+
+Full details are available in the upstream docs regarding the `Angular Commit Message Conventions <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines>`_.
+The key factor is that the first line of the commit message must follow this format:
+
+.. code-block::
+
+   type(scope): subject
+
+
+* E.g. ``docs(contributing): add commit message formatting instructions``.
+
+Besides the version bump, the changelog and release notes are formatted accordingly.
+So based on the example above:
+
+..
+
+   .. raw:: html
+
+      <h3>Documentation</h3>
+
+   * **contributing:** add commit message formatting instructions
+
+
+* The ``type`` translates into a ``Documentation`` sub-heading.
+* The ``(scope):`` will be shown in bold text without the brackets.
+* The ``subject`` follows the ``scope`` as standard text.
+
+Linting commit messages in Travis CI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This formula uses `commitlint <https://github.com/conventional-changelog/commitlint>`_ for checking commit messages during CI testing.
+This ensures that they are in accordance with the ``semantic-release`` settings.
+
+For more details about the default settings, refer back to the ``commitlint`` `reference rules <https://conventional-changelog.github.io/commitlint/#/reference-rules>`_.
+
+Relationship between commit type and version bump
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This formula applies some customisations to the defaults, as outlined in the table below,
+based upon the `type <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#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
+
+Use ``BREAKING CHANGE`` to trigger a ``major`` version change
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding ``BREAKING CHANGE`` to the footer of the extended description of the commit message will **always** trigger a ``major`` version change, no matter which type has been used.
+This will be appended to the changelog and release notes as well.
+To preserve good formatting of these notes, the following format is prescribed:
+
+* ``BREAKING CHANGE: <explanation in paragraph format>.``
+
+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.
+
+Documentation
+-------------
+
+Toolchain
+^^^^^^^^^
+
+The documentation for this formula is written in
+`reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_
+(also known as RST, ReST, or reST).
+It is built by
+`Sphinx <https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
+and hosted on
+`Read the Docs <https://en.wikipedia.org/wiki/Read_the_Docs>`_.
+
+Adding a new page
+^^^^^^^^^^^^^^^^^
+
+Adding a new page involves two steps:
+
+#. Use the
+   :ref:`provided page template <saltstack_formulas_rst_page_template>`
+   to create a new page.
+#. Add the page name under the ``toctree`` list in ``index.rst``.
+
+   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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _saltstack_formulas_rst_page_template
+
+Use the following template when creating a new page.
+This ensures consistency across the documentation for this formula.
+The heading symbols have been selected in accordance to the output rendered by the
+`Markdown to reStructuredText converter <https://github.com/miyakogi/m2r#restrictions>`_
+we are using for some of the pages of this documentation.
+
+.. code-block:: rst
+
+   .. _template:
+
+   [Page title]
+   ============
+
+   [Introductory paragraph]
+
+   .. contents:: **Table of Contents**
+
+   [Heading 2]
+   -----------
+
+   [Heading 3]
+   ^^^^^^^^^^^
+
+   [Heading 4]
+   ~~~~~~~~~~~
+
+   [Heading 5]
+   """""""""""
+
+   [Heading 6]
+   ###########
+
+#. The first line is an anchor that can be used to link back to (the top of)
+   this file.
+
+   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 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.
+
+   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.
+
+Obviously, it is not necessary to follow the steps in the order above.
+For example, it is usually easier to write the ``[Introductory paragraph]``
+at the end.
+