Skip to content

Commit 9044a92

Browse files
alxwralxwr
committed
chore(semantic-release): take last steps towards semantic release
1 parent b2c9cf1 commit 9044a92

4 files changed

Lines changed: 291 additions & 16 deletions

File tree

‎FORMULA‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name: template
2+
os: Debian, Ubuntu, Raspbian, RedHat, Fedora, CentOS, Suse, openSUSE, Gentoo, Funtoo, Arch, Manjaro, Alpine, FreeBSD, OpenBSD, Solaris, SmartOS, Windows, MacOS
3+
os_family: Debian, RedHat, Suse, Gentoo, Arch, Alpine, FreeBSD, OpenBSD, Solaris, Windows, MacOS
4+
version: 1.0.0
5+
release: 1
6+
minimum_version: 2018.3
7+
summary: OpenVPN formula
8+
description: Formula to use manage OpenVPN
9+
top_level_dir: openvpn

‎docs/CONTRIBUTING.rst‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
.. _contributing:
2+
3+
How to contribute
4+
=================
5+
6+
This document will eventually outline all aspects of guidance to make your contributing experience a fruitful and enjoyable one.
7+
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.
8+
It also covers how to contribute to this *formula's documentation*.
9+
10+
.. contents:: **Table of Contents**
11+
12+
Overview
13+
--------
14+
15+
Submitting a pull request is more than just code!
16+
To achieve a quality product, the *tests* and *documentation* need to be updated as well.
17+
An excellent pull request will include these in the changes, wherever relevant.
18+
19+
Commit message formatting
20+
-------------------------
21+
22+
Since every type of change requires making Git commits,
23+
we will start by covering the importance of ensuring that all of your commit
24+
messages are in the correct format.
25+
26+
Automation of multiple processes
27+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
28+
29+
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.
30+
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.
31+
32+
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>`_.
33+
The key factor is that the first line of the commit message must follow this format:
34+
35+
.. code-block::
36+
37+
type(scope): subject
38+
39+
40+
* E.g. ``docs(contributing): add commit message formatting instructions``.
41+
42+
Besides the version bump, the changelog and release notes are formatted accordingly.
43+
So based on the example above:
44+
45+
..
46+
47+
.. raw:: html
48+
49+
<h3>Documentation</h3>
50+
51+
* **contributing:** add commit message formatting instructions
52+
53+
54+
* The ``type`` translates into a ``Documentation`` sub-heading.
55+
* The ``(scope):`` will be shown in bold text without the brackets.
56+
* The ``subject`` follows the ``scope`` as standard text.
57+
58+
Linting commit messages in Travis CI
59+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
60+
61+
This formula uses `commitlint <https://github.com/conventional-changelog/commitlint>`_ for checking commit messages during CI testing.
62+
This ensures that they are in accordance with the ``semantic-release`` settings.
63+
64+
For more details about the default settings, refer back to the ``commitlint`` `reference rules <https://conventional-changelog.github.io/commitlint/#/reference-rules>`_.
65+
66+
Relationship between commit type and version bump
67+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
68+
69+
This formula applies some customisations to the defaults, as outlined in the table below,
70+
based upon the `type <https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type>`_ of the commit:
71+
72+
.. list-table::
73+
:name: commit-type-vs-version-bump
74+
:header-rows: 1
75+
:stub-columns: 0
76+
:widths: 1,2,3,1,1
77+
78+
* - Type
79+
- Heading
80+
- Description
81+
- Bump (default)
82+
- Bump (custom)
83+
* - ``build``
84+
- Build System
85+
- Changes related to the build system
86+
- –
87+
-
88+
* - ``chore``
89+
- –
90+
- Changes to the build process or auxiliary tools and libraries such as
91+
documentation generation
92+
- –
93+
-
94+
* - ``ci``
95+
- Continuous Integration
96+
- Changes to the continuous integration configuration
97+
- –
98+
-
99+
* - ``docs``
100+
- Documentation
101+
- Documentation only changes
102+
- –
103+
- 0.0.1
104+
* - ``feat``
105+
- Features
106+
- A new feature
107+
- 0.1.0
108+
-
109+
* - ``fix``
110+
- Bug Fixes
111+
- A bug fix
112+
- 0.0.1
113+
-
114+
* - ``perf``
115+
- Performance Improvements
116+
- A code change that improves performance
117+
- 0.0.1
118+
-
119+
* - ``refactor``
120+
- Code Refactoring
121+
- A code change that neither fixes a bug nor adds a feature
122+
- –
123+
- 0.0.1
124+
* - ``revert``
125+
- Reverts
126+
- A commit used to revert a previous commit
127+
- –
128+
- 0.0.1
129+
* - ``style``
130+
- Styles
131+
- Changes that do not affect the meaning of the code (white-space,
132+
formatting, missing semi-colons, etc.)
133+
- –
134+
- 0.0.1
135+
* - ``test``
136+
- Tests
137+
- Adding missing or correcting existing tests
138+
- –
139+
- 0.0.1
140+
141+
Use ``BREAKING CHANGE`` to trigger a ``major`` version change
142+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
143+
144+
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.
145+
This will be appended to the changelog and release notes as well.
146+
To preserve good formatting of these notes, the following format is prescribed:
147+
148+
* ``BREAKING CHANGE: <explanation in paragraph format>.``
149+
150+
An example of that:
151+
152+
.. code-block:: git
153+
154+
...
155+
156+
BREAKING CHANGE: With the removal of all of the `.sls` files under
157+
`openvpn/package`, this formula no longer supports the installation of
158+
packages.
159+

‎docs/README.rst‎

Lines changed: 93 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,133 @@
1-
=======
2-
openvpn
3-
=======
1+
.. _readme:
2+
3+
openvpn-formula
4+
===============
5+
6+
7+
|img_travis| |img_sr|
8+
9+
.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/openvpn-formula.svg?branch=master
10+
:alt: Travis CI Build Status
11+
:scale: 100%
12+
:target: https://travis-ci.com/saltstack-formulas/openvpn-formula
13+
.. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
14+
:alt: Semantic Release
15+
:scale: 100%
16+
:target: https://github.com/semantic-release/semantic-release
417

518
Formula to install and configure openvpn server and client.
619

7-
.. note::
20+
.. contents:: **Table of Contents**
21+
22+
General notes
23+
-------------
24+
25+
See the full `SaltStack Formulas installation and usage instructions
26+
<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
27+
28+
If you are interested in writing or contributing to formulas, please pay attention to the `Writing Formula Section
29+
<https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>`_.
30+
31+
If you want to use this formula, please pay attention to the ``FORMULA`` file and/or ``git tag``,
32+
which contains the currently released version. This formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
33+
34+
See `Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>`_ for more details.
35+
36+
Contributing to this repo
37+
-------------------------
38+
39+
**Commit message formatting is significant!!**
40+
41+
Please see :ref:`How to contribute <CONTRIBUTING>` for more details.
842

9-
See the full `Salt Formulas installation and usage instructions
10-
<http://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>`_.
1143

1244
Available states
13-
================
45+
----------------
1446

1547
.. contents::
1648
:local:
1749

1850
``openvpn``
19-
--------
51+
^^^^^^^^^^^
2052

2153
Installs OpenVPN.
2254

2355
``openvpn.config``
24-
--------
56+
^^^^^^^^^^^^^^^^^^
2557

2658
Configures OpenVPN client and server. Multiple clients and servers are possible.
2759

2860
``openvpn.gui``
29-
--------
61+
^^^^^^^^^^^^^^^
3062

3163
Configures OpenVPN GUI (Windows only). Sets global registry settings as described `here <https://github.com/OpenVPN/openvpn-gui/#registry-values-affecting-the-openvpn-gui-operation>`_.
3264

3365
``openvpn.adapters``
34-
--------
66+
^^^^^^^^^^^^^^^^^^^^
3567

3668
Manages TAP-Windows device adapters (Windows only). Ensures that any devices specified with ``dev_node`` in pillar exist.
3769

3870
``openvpn.ifconfig_pool_persist``
39-
---------------------------------
71+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4072

4173
Installs and configures an ifconfig_pool_persist file. Used to assign host IPs.
4274

4375
``openvpn.network_manager_networks``
44-
------------------------------------
76+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4577

4678
Don't setup a OpenVPN client service, but add ready-to-use NetworkManager configurations.
4779

48-
Example
49-
=======
80+
Examples
81+
--------
5082

5183
See *openvpn/pillar.example*.
5284

5385
Notes
54-
=====
86+
-----
5587

5688
This formula does can optionally deploy certificates and keys, but does not generate them. This must be done manually or with another formula.
89+
90+
Testing
91+
-------
92+
93+
Linux testing is done with ``kitchen-salt``.
94+
95+
Requirements
96+
^^^^^^^^^^^^
97+
98+
* Ruby
99+
* Docker
100+
101+
.. code-block:: bash
102+
103+
$ gem install bundler
104+
$ bundle install
105+
$ bin/kitchen test [platform]
106+
107+
Where ``[platform]`` is the platform name defined in ``kitchen.yml``,
108+
e.g. ``debian-9-2019-2-py3``.
109+
110+
``bin/kitchen converge``
111+
^^^^^^^^^^^^^^^^^^^^^^^^
112+
113+
Creates the docker instance and runs the ``openvpn`` main state, ready for testing.
114+
115+
``bin/kitchen verify``
116+
^^^^^^^^^^^^^^^^^^^^^^
117+
118+
Runs the ``inspec`` tests on the actual instance.
119+
120+
``bin/kitchen destroy``
121+
^^^^^^^^^^^^^^^^^^^^^^^
122+
123+
Removes the docker instance.
124+
125+
``bin/kitchen test``
126+
^^^^^^^^^^^^^^^^^^^^
127+
128+
Runs all of the stages above in one go: i.e. ``destroy`` + ``converge`` + ``verify`` + ``destroy``.
129+
130+
``bin/kitchen login``
131+
^^^^^^^^^^^^^^^^^^^^^
132+
133+
Gives you SSH access to the instance for manual testing.

‎pre-commit_semantic-release.sh‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
#!/bin/sh
2+
3+
###############################################################################
4+
# (A) Update `FORMULA` with `${nextRelease.version}`
5+
###############################################################################
6+
sed -i -e "s_^\(version:\).*_\1 ${1}_" FORMULA
7+
8+
9+
###############################################################################
10+
# (B) Use `m2r` to convert automatically produced `.md` docs to `.rst`
11+
###############################################################################
12+
13+
# Install `m2r`
14+
sudo -H pip install m2r
15+
16+
# Copy and then convert the `.md` docs
17+
cp *.md docs/
18+
cd docs/
19+
m2r --overwrite *.md
20+
21+
# Change excess `H1` headings to `H2` in converted `CHANGELOG.rst`
22+
sed -i -e '/^=.*$/s/=/-/g' CHANGELOG.rst
23+
sed -i -e '1,4s/-/=/g' CHANGELOG.rst
24+
25+
# Use for debugging output, when required
26+
# cat AUTHORS.rst
27+
# cat CHANGELOG.rst
28+
29+
# Return back to the main directory
30+
cd ..

0 commit comments

Comments
 (0)