* Update docs * Add auxiliar scripts * Add missing headerstags/v0.8.1
*.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 | ||||
.kitchen.local.yml | .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? |
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 |
Copyright (c) 2013-2015 Salt Stack Formulas | |||||
Copyright (c) 2014 Salt Stack Formulas | |||||
Licensed under the Apache License, Version 2.0 (the "License"); | Licensed under the Apache License, Version 2.0 (the "License"); | ||||
you may not use this file except in compliance with the License. | you may not use this file except in compliance with the License. |
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``. | |||||
module.exports = { | |||||
extends: ['@commitlint/config-conventional'], | |||||
}; |
.. _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. |
.. _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 |
# -*- coding: utf-8 -*- | |||||
# vim: ft=yaml | |||||
--- | |||||
apt: | apt: | ||||
# Set the right keyring for the distro (ie ubuntu-keyring or ...) | # Set the right keyring for the distro (ie ubuntu-keyring or ...) | ||||
keyring_package: debian-archive-keyring | keyring_package: debian-archive-keyring |
#!/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 .. |
// 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'}, | |||||
]; |
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 | |||||
}, | |||||
}, | |||||
}, | |||||
}; |