chore: follow template-formula guidelines

* Update docs
* Add auxiliar scripts
* Add missing headers

.gitignore

@@ -1,3 +1,113 @@
-*.swp
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a packager
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
 .kitchen
 .kitchen.local.yml
+kitchen.local.yml
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# Bundler
+Gemfile.lock
+
+# copied `.md` files used for conversion to `.rst` using `m2r`
+docs/*.md
+
+# Vim
+*.sw?

FORMULA

@@ -0,0 +1,9 @@
+name: apt
+os: Debian, Ubuntu, Raspbian 
+os_family: Debian
+version: 0.2.0
+release: 1
+minimum_version: 2017.7
+summary: Apt formula
+description: Formula to configure APT and related resources
+top_level_dir: apt

LICENSE

@@ -1,4 +1,4 @@
-   Copyright (c) 2013-2015 Salt Stack Formulas
+   Copyright (c) 2014 Salt Stack Formulas
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.rst

@@ -1,68 +0,0 @@
-apt
-===
-
-Formulas to update, upgrade, and dist-upgrade within apt.
-
-.. note::
-
-    See the full `Salt Formulas installation and usage instructions
-    <http://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
-
-Available states
-================
-
-.. contents::
-    :local:
-
-``apt.dist_upgrade``
---------------------
-
-Runs ``apt-get -y dist-upgrade``.
-
-``apt.update``
---------------
-
-Runs ``apt-get -y update``.
-
-``apt.upgrade``
----------------
-
-Runs ``apt-get -y upgrade``.
-
-``apt.repositories``
---------------------
-
-Allows you to configure and manage repositories from pillar. Check ``pillar.example``
-to see possible values. If used and no repositories are provided, sane default
-values from ``map.jinja`` are used.
-
-Check https://wiki.debian.org/SourcesList for an explanation about the resulting
-files structure.
-
-``apt.preferences``
--------------------
-
-Allows you to configure and manage apt's preferences from pillar. Check
-``pillar.example`` to see possible values. If used and no repositories are
-provided, sane default values from ``map.jinja`` are used.
-
-Check https://wiki.debian.org/AptPreferences?action=show&redirect=preferences
-and ``man 5 apt_preferences`` for an explanation about the resulting files structure.
-
-``apt.ppa``
------------
-Installs ``python-software-properties``
-(``$ /usr/bin/apt-add-repository ppa:user/repository``).
-
-``apt.unattended``
-------------------
-Installs and configures ``unattended-upgrades``
-
-``apt.transports.debtorrent``
--------------------------------
-Installs ``apt-transport-debtorrent``.
-
-``apt.transports.https``
---------------------------
-Installs ``apt-transport-https``.
-

commitlint.config.js

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

docs/CONTRIBUTING.rst

@@ -0,0 +1,158 @@
+.. _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.

docs/README.rst

@@ -0,0 +1,131 @@
+.. _readme:
+
+apt
+===
+
+|img_travis| |img_sr|
+
+.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/apt-formula.svg?branch=master
+   :alt: Travis CI Build Status
+   :scale: 100%
+   :target: https://travis-ci.com/saltstack-formulas/apt-formula
+.. |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
+
+A formula to configure and manage update, upgrade, and dist-upgrade within apt.
+
+.. contents:: **Table of Contents**
+
+General notes
+-------------
+
+See the full `SaltStack Formulas installation and usage instructions
+<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
+
+If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
+<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
+
+If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
+which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
+
+See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
+
+Contributing to this repo
+-------------------------
+
+**Commit message formatting is significant!!**
+
+Please see :ref:`How to contribute <CONTRIBUTING>` for more details.
+
+Available states
+----------------
+
+.. contents::
+   :local:
+
+``apt.dist_upgrade``
+^^^^^^^^^^^^^^^^^^^^
+
+Runs ``apt-get -y dist-upgrade``.
+
+``apt.update``
+^^^^^^^^^^^^^^
+
+Runs ``apt-get -y update``.
+
+``apt.upgrade``
+^^^^^^^^^^^^^^^
+
+Runs ``apt-get -y upgrade``.
+
+``apt.repositories``
+^^^^^^^^^^^^^^^^^^^^
+
+Allows you to configure and manage repositories from pillar. Check ``pillar.example``
+to see possible values. If used and no repositories are provided, sane default
+values from ``map.jinja`` are used.
+
+Check https://wiki.debian.org/SourcesList for an explanation about the resulting
+files structure.
+
+``apt.preferences``
+^^^^^^^^^^^^^^^^^^^
+
+Allows you to configure and manage apt's preferences from pillar. Check
+``pillar.example`` to see possible values. If used and no repositories are
+provided, sane default values from ``map.jinja`` are used.
+
+Check https://wiki.debian.org/AptPreferences?action=show&redirect=preferences
+and ``man 5 apt_preferences`` for an explanation about the resulting files structure.
+
+``apt.ppa``
+^^^^^^^^^^^
+Installs ``python-software-properties``
+(``$ /usr/bin/apt-add-repository ppa:user/repository``).
+
+``apt.unattended``
+^^^^^^^^^^^^^^^^^^
+Installs and configures ``unattended-upgrades``
+
+``apt.transports.debtorrent``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Installs ``apt-transport-debtorrent``.
+
+``apt.transports.https``
+^^^^^^^^^^^^^^^^^^^^^^^^
+Installs ``apt-transport-https``. **Note that `apt-transport-https` has been deprecated
+since Debian 9 and it's now a dummy package**
+
+Testing
+-------
+
+Linux testing is done with ``kitchen-salt``.
+
+``kitchen converge``
+^^^^^^^^^^^^^^^^^^^^
+
+Creates the docker instance and runs the ``apt`` main state, ready for testing.
+
+``kitchen verify``
+^^^^^^^^^^^^^^^^^^
+
+Runs the ``inspec`` tests on the actual instance.
+
+``kitchen destroy``
+^^^^^^^^^^^^^^^^^^^
+
+Removes the docker instance.
+
+``kitchen test``
+^^^^^^^^^^^^^^^^
+
+Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
+
+``kitchen login``
+^^^^^^^^^^^^^^^^^
+
+Gives you SSH access to the instance for manual testing.
+
+.. vim: fenc=utf-8 spell spl=en cc=100 tw=99 fo=want sts=2 sw=2 et

pillar.example

@@ -1,3 +1,6 @@
+# -*- coding: utf-8 -*-
+# vim: ft=yaml
+---
 apt:
   # Set the right keyring for the distro (ie ubuntu-keyring or ...)
   keyring_package: debian-archive-keyring

pre-commit_semantic-release.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+
+###############################################################################
+# (A) Update `FORMULA` with `${nextRelease.version}`
+###############################################################################
+sed -i -e "s_^\(version:\).*_\1 ${1}_" FORMULA
+
+
+###############################################################################
+# (B) Use `m2r` to convert automatically produced `.md` docs to `.rst`
+###############################################################################
+
+# Install `m2r`
+sudo -H pip install m2r
+
+# Copy and then convert the `.md` docs
+cp *.md docs/
+cd docs/
+m2r --overwrite *.md
+
+# Change excess `H1` headings to `H2` in converted `CHANGELOG.rst`
+sed -i -e '/^=.*$/s/=/-/g' CHANGELOG.rst
+sed -i -e '1,4s/-/=/g' CHANGELOG.rst
+
+# Use for debugging output, when required
+# cat AUTHORS.rst
+# cat CHANGELOG.rst
+
+# Return back to the main directory
+cd ..

release-rules.js

@@ -0,0 +1,18 @@
+// No release is triggered for the types commented out below.
+// Commits using these types will be incorporated into the next release.
+//
+// NOTE: Any changes here must be reflected in `CONTRIBUTING.md`.
+module.exports = [
+  {breaking: true, release: 'major'},
+  // {type: 'build', release: 'patch'},
+  // {type: 'chore', release: 'patch'},
+  // {type: 'ci', release: 'patch'},
+  {type: 'docs', release: 'patch'},
+  {type: 'feat', release: 'minor'},
+  {type: 'fix', release: 'patch'},
+  {type: 'perf', release: 'patch'},
+  {type: 'refactor', release: 'patch'},
+  {type: 'revert', release: 'patch'},
+  {type: 'style', release: 'patch'},
+  {type: 'test', release: 'patch'},
+];

release.config.js

@@ -0,0 +1,106 @@
+module.exports = {
+  branch: 'master',
+  plugins: [
+      ['@semantic-release/commit-analyzer', {
+        preset: 'angular',
+        releaseRules: './release-rules.js',
+      }],
+      '@semantic-release/release-notes-generator',
+      ['@semantic-release/changelog', {
+        changelogFile: 'CHANGELOG.md',
+        changelogTitle: '# Changelog',
+      }],
+      ['@semantic-release/exec', {
+        prepareCmd: 'sh ./pre-commit_semantic-release.sh ${nextRelease.version}',
+      }],
+      ['@semantic-release/git', {
+        assets: ['*.md', 'docs/*.rst', 'FORMULA'],
+      }],
+      '@semantic-release/github',
+  ],
+  generateNotes: {
+    preset: 'angular',
+    writerOpts: {
+      // Required due to upstream bug preventing all types being displayed.
+      // Bug: https://github.com/conventional-changelog/conventional-changelog/issues/317
+      // Fix: https://github.com/conventional-changelog/conventional-changelog/pull/410
+      transform: (commit, context) => {
+          const issues = []
+
+          commit.notes.forEach(note => {
+              note.title = `BREAKING CHANGES`
+          })
+
+          // NOTE: Any changes here must be reflected in `CONTRIBUTING.md`.
+          if (commit.type === `feat`) {
+              commit.type = `Features`
+          } else if (commit.type === `fix`) {
+              commit.type = `Bug Fixes`
+          } else if (commit.type === `perf`) {
+              commit.type = `Performance Improvements`
+          } else if (commit.type === `revert`) {
+              commit.type = `Reverts`
+          } else if (commit.type === `docs`) {
+              commit.type = `Documentation`
+          } else if (commit.type === `style`) {
+              commit.type = `Styles`
+          } else if (commit.type === `refactor`) {
+              commit.type = `Code Refactoring`
+          } else if (commit.type === `test`) {
+              commit.type = `Tests`
+          } else if (commit.type === `build`) {
+              commit.type = `Build System`
+          // } else if (commit.type === `chore`) {
+          //     commit.type = `Maintenance`
+          } else if (commit.type === `ci`) {
+              commit.type = `Continuous Integration`
+          } else {
+              return
+          }
+
+          if (commit.scope === `*`) {
+              commit.scope = ``
+          }
+
+          if (typeof commit.hash === `string`) {
+              commit.hash = commit.hash.substring(0, 7)
+          }
+
+          if (typeof commit.subject === `string`) {
+              let url = context.repository
+                  ? `${context.host}/${context.owner}/${context.repository}`
+                  : context.repoUrl
+              if (url) {
+                  url = `${url}/issues/`
+                  // Issue URLs.
+                  commit.subject = commit.subject.replace(/#([0-9]+)/g, (_, issue) => {
+                      issues.push(issue)
+                      return `[#${issue}](${url}${issue})`
+                  })
+              }
+              if (context.host) {
+                  // User URLs.
+                  commit.subject = commit.subject.replace(/\B@([a-z0-9](?:-?[a-z0-9/]){0,38})/g, (_, username) => {
+                  if (username.includes('/')) {
+                      return `@${username}`
+                  }
+
+                  return `[@${username}](${context.host}/${username})`
+                  })
+              }
+          }
+
+          // remove references that already appear in the subject
+          commit.references = commit.references.filter(reference => {
+              if (issues.indexOf(reference.issue) === -1) {
+                  return true
+              }
+
+              return false
+          })
+
+          return commit
+      },
+    },
+  },
+};