dist: bionic | dist: bionic | ||||
stages: | stages: | ||||
- test | - test | ||||
- lint | |||||
- name: release | |||||
if: branch = master AND type != pull_request | |||||
sudo: required | sudo: required | ||||
cache: bundler | cache: bundler | ||||
script: | script: | ||||
- bin/kitchen verify ${INSTANCE} | - bin/kitchen verify ${INSTANCE} | ||||
jobs: | |||||
include: | |||||
# Define the `lint` stage (runs `yamllint` and `commitlint`) | |||||
- stage: lint | |||||
language: node_js | |||||
node_js: lts/* | |||||
before_install: skip | |||||
script: | |||||
# Install and run `yamllint` | |||||
# Need at least `v1.17.0` for the `yaml-files` setting | |||||
- pip install --user yamllint>=1.17.0 | |||||
- yamllint -s . | |||||
# Install and run `commitlint` | |||||
- 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 |
# -*- coding: utf-8 -*- | |||||
# vim: ft=yaml | |||||
--- | |||||
# Extend the `default` configuration provided by `yamllint` | |||||
extends: default | |||||
# Files to ignore completely | |||||
# 1. All YAML files under directory `node_modules/`, introduced during the Travis run | |||||
# 2. Any SLS files under directory `test/`, which are actually state files | |||||
ignore: | | |||||
node_modules/ | |||||
test/**/states/**/*.sls | |||||
yaml-files: | |||||
# Default settings | |||||
- '*.yaml' | |||||
- '*.yml' | |||||
- .yamllint | |||||
# SaltStack Formulas additional settings | |||||
- '*.example' | |||||
- test/**/*.sls | |||||
rules: | |||||
empty-values: | |||||
forbid-in-block-mappings: true | |||||
forbid-in-flow-mappings: true | |||||
line-length: | |||||
# Increase from default of `80` | |||||
# Based on https://github.com/PyCQA/flake8-bugbear#opinionated-warnings (`B950`) | |||||
max: 88 |
name: apt-cacher | |||||
os: Debian, Ubuntu | |||||
os_family: Debian | |||||
version: 0.1.0 | |||||
release: 1 | |||||
minimum_version: 2017.7 | |||||
summary: AptCacher formula | |||||
description: Formula to use to install and configure apt-cacher | |||||
top_level_dir: apt-cacher |
apt-cacher | |||||
========== | |||||
Formulas to install the apt-cacher package or to configure clients to | |||||
use a apt-cacher proxy. | |||||
It also supports apt-cacher-ng, the successor of apt-cacher: | |||||
https://www.unix-ag.uni-kl.de/~bloch/acng | |||||
.. note:: | |||||
See the full `Salt Formulas installation and usage instructions | |||||
<http://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_. | |||||
Requirements | |||||
------------ | |||||
apt-cacher requires apache formula (apt-cacher-ng does not, as it runs in standalone mode) | |||||
`apache-formula <https://github.com/saltstack-formulas/apache-formula>`_ | |||||
Available states | |||||
================ | |||||
.. contents:: | |||||
:local: | |||||
``apt-cacher.server`` | |||||
-------------------- | |||||
Installs the apt-cacher package | |||||
``apt-cacher.client`` | |||||
--------------------- | |||||
Sets up the system to use the apt-cacher server as the caching proxy | |||||
``apt-cacher.ng.server`` | |||||
------- | |||||
Install and configure apt-cacher-ng. | |||||
Supports Debian(ish) distributions and FreeBSD. | |||||
``apt-cacher.ng.client`` | |||||
------------ | |||||
Sets up the system to use the apt-cacher-ng server as the caching proxy |
# -*- coding: utf-8 -*- | |||||
# vim: ft=yaml | |||||
--- | |||||
apt_cacher_ng: | apt_cacher_ng: | ||||
server_address: localhost | server_address: localhost | ||||
server_bind_address: 0.0.0.0 | server_bind_address: 0.0.0.0 | ||||
server_port: 3142 | server_port: 3142 | ||||
server_extra_config: | |||||
server_extra_config: null | |||||
server_config: /etc/apt-cacher-ng/zzz_acng.conf | server_config: /etc/apt-cacher-ng/zzz_acng.conf | ||||
server_cache_dir: /var/cache/apt-cacher-ng | server_cache_dir: /var/cache/apt-cacher-ng | ||||
server_log_dir: /var/log/apt-cacher-ng | server_log_dir: /var/log/apt-cacher-ng |
# -*- coding: utf-8 -*- | |||||
# vim: ft=yaml | |||||
--- | |||||
Debian: {} | Debian: {} | ||||
FreeBSD: | FreeBSD: | ||||
credentials: /usr/local/etc/apt-cacher-ng/security.conf | credentials: /usr/local/etc/apt-cacher-ng/security.conf | ||||
root_group: wheel | root_group: wheel | ||||
# We stick to the Debian user name in order to | # We stick to the Debian user name in order to | ||||
# further separate apt-cacher-ng from other potentially present | # further separate apt-cacher-ng from other potentially present | ||||
# services running as 'proxy'. | # services running as 'proxy'. | ||||
#user: proxy | |||||
#group: proxy | |||||
# user: proxy | |||||
# group: proxy |
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-cacher-formula | |||||
================== | |||||
|img_travis| |img_sr| | |||||
.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/apt-cacher-formula.svg?branch=master | |||||
:alt: Travis CI Build Status | |||||
:scale: 100% | |||||
:target: https://travis-ci.com/saltstack-formulas/apt-cacher-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 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. | |||||
.. 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-cacher.server`` | |||||
^^^^^^^^^^^^^^^^^^^^^ | |||||
Installs the apt-cacher package. | |||||
``apt-cacher.client`` | |||||
^^^^^^^^^^^^^^^^^^^^^ | |||||
Sets up the system to use the apt-cacher server as the caching proxy. | |||||
``apt-cacher.ng.server`` | |||||
^^^^^^^^^^^^^^^^^^^^^^^^ | |||||
Install and configure apt-cacher-ng. | |||||
Supports Debian(ish) distributions and FreeBSD. | |||||
``apt-cacher.ng.client`` | |||||
^^^^^^^^^^^^^^^^^^^^^^^^ | |||||
Sets up the system to use the apt-cacher-ng server as the caching proxy. | |||||
Testing | |||||
------- | |||||
Linux testing is done with ``kitchen-salt``. | |||||
Requirements | |||||
^^^^^^^^^^^^ | |||||
* Ruby | |||||
* Docker | |||||
.. code-block:: bash | |||||
$ gem install bundler | |||||
$ bundle install | |||||
$ bin/kitchen test [platform] | |||||
Where ``[platform]`` is the platform name defined in ``kitchen.yml``, | |||||
e.g. ``debian-9-2019-2-py3``. | |||||
``bin/kitchen converge`` | |||||
^^^^^^^^^^^^^^^^^^^^^^^^ | |||||
Creates the docker instance and runs the ``apt-cacher`` main state, ready for testing. | |||||
``bin/kitchen verify`` | |||||
^^^^^^^^^^^^^^^^^^^^^^ | |||||
Runs the ``inspec`` tests on the actual instance. | |||||
``bin/kitchen destroy`` | |||||
^^^^^^^^^^^^^^^^^^^^^^^ | |||||
Removes the docker instance. | |||||
``bin/kitchen test`` | |||||
^^^^^^^^^^^^^^^^^^^^ | |||||
Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``. | |||||
``bin/kitchen login`` | |||||
^^^^^^^^^^^^^^^^^^^^^ | |||||
Gives you SSH access to the instance for manual testing. |
# -*- coding: utf-8 -*- | |||||
# vim: ft=yaml | |||||
--- | |||||
apt_cacher: | apt_cacher: | ||||
host: cacher.mycompany.com | host: cacher.mycompany.com | ||||
admin_email: admin@mycompany.com | admin_email: admin@mycompany.com | ||||
group: www-data | group: www-data | ||||
user: www-data | user: www-data | ||||
#ip for upstream connection | |||||
# ip for upstream connection | |||||
interface: 10.10.0.1 | interface: 10.10.0.1 | ||||
apt_cacher_ng: | apt_cacher_ng: | ||||
- 192.168.0.1 | - 192.168.0.1 | ||||
- host.example.test | - host.example.test | ||||
## | |||||
# require/require_in/include example | |||||
# See https://github.com/saltstack-formulas/apt-cacher-formula/pull/12 for details | |||||
apt_cacher_ng: | |||||
... | |||||
include: | |||||
# custom states which must run before apt-cacher.ng.server | |||||
- repositories.sources | |||||
- apt-cacher-ng-fixes.server | |||||
require: | |||||
# custom states: i.e. a file which depends on the apt-cacher-ng package, | |||||
# but is required by the apt-cacher-ng server. | |||||
- 'file: /etc/apt-cacher-ng/backends_debian' | |||||
require_in: | |||||
# custom states: i.e. Debian package repos | |||||
- 'pkgrepo: deb jessie-backports' | |||||
- 'pkgrepo: deb-src jessie-backports' | |||||
# yamllint disable-line rule:comments-indentation | |||||
# Example for require/require_in/include | |||||
# See: https://github.com/saltstack-formulas/apt-cacher-formula/pull/12 for details | |||||
# apt_cacher_ng: | |||||
# ... | |||||
# include: | |||||
# # custom states which must run before apt-cacher.ng.server | |||||
# - repositories.sources | |||||
# - apt-cacher-ng-fixes.server | |||||
# require: | |||||
# # custom states: i.e. a file which depends on the apt-cacher-ng package, | |||||
# # but is required by the apt-cacher-ng server. | |||||
# - 'file: /etc/apt-cacher-ng/backends_debian' | |||||
# require_in: | |||||
# # custom states: i.e. Debian package repos | |||||
# - 'pkgrepo: deb jessie-backports' | |||||
# - 'pkgrepo: deb-src jessie-backports' |
#!/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 | |||||
}, | |||||
}, | |||||
}, | |||||
}; |