docs(contributing): add commit message formatting instructions

CONTRIBUTING.md

@@ -1 +1,46 @@
 # How to contribute
+
+## Commit message formatting
+
+This repo 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:
+
+```
+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:
+
+> ### Documentation
+> 
+> * **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.
+
+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:
+
+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
+
+* 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.
+

README.rst

@@ -20,11 +20,20 @@ See the full `Salt Formulas installation and usage instructions
 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 ``VERSION`` file and/or ``git tag``,
-wich contains the currently released version. Formula is versioned according to `Semantic Versioning <http://semver.org/>`_.
+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 `CONTRIBUTING <CONTRIBUTING.md>`_ for more details.
+
+
 Available states
 ================
 

release-rules.js

@@ -1,5 +1,7 @@
 // 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'},

release.config.js

@@ -31,6 +31,7 @@ module.exports = {
               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`) {
@@ -49,6 +50,8 @@ module.exports = {
               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 {