diff --git a/.travis.yml b/.travis.yml index f25c307..1ca90a4 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,3 +1,9 @@ +stages: + - test + - commitlint + - name: release + if: branch = master AND type != pull_request + sudo: required language: ruby cache: bundler @@ -15,3 +21,37 @@ env: - PLATFORM=amazon script: bundle exec kitchen test ${PLATFORM} + +jobs: + include: + # Define the commitlint stage + - stage: commitlint + language: node_js + node_js: lts/* + before_install: skip + script: + - 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 + diff --git a/FORMULA b/FORMULA new file mode 100644 index 0000000..fceebd1 --- /dev/null +++ b/FORMULA @@ -0,0 +1,9 @@ +name: vault +os: Debian, Ubuntu, RedHat, Fedora, CentOS, Amazon +os_family: Debian, RedHat +version: 0.5.0 +release: 1 +minimum_version: 2018.3 +summary: Vault formula +description: Formula to install and configure Hashicorp Vault +top_level_dir: vault diff --git a/commitlint.config.js b/commitlint.config.js new file mode 100644 index 0000000..2f9d1aa --- /dev/null +++ b/commitlint.config.js @@ -0,0 +1,3 @@ +module.exports = { + extends: ['@commitlint/config-conventional'], +}; diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst new file mode 100644 index 0000000..5da9ae8 --- /dev/null +++ b/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 `_ 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 `_. +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 + +

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. + +Linting commit messages in Travis CI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This formula uses `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 `_. + +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 `_ 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: .`` + +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. diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000..4617efc --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,21 @@ +/* + Override styles for in-use Sphinx theme +*/ + +/* The next two `.wy`-based rules are specifically needed for the dealing with */ +/* the `sphinx_rtd_theme` bug where long lines do not wrap in tables */ + +/* override table width restrictions */ +.wy-table-responsive table th +, .wy-table-responsive table td +{ + /* !important prevents the common CSS stylesheets from + overriding this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; +} + +.wy-table-responsive +{ + overflow: visible !important; +} + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..afc8bd3 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,173 @@ +# -*- coding: utf-8 -*- +"""Configuration file for the Sphinx documentation builder. + +This file does only contain a selection of the most common options. For a +full list see the documentation: + +* http://www.sphinx-doc.org/en/stable/config + +""" + +from __future__ import division, print_function, unicode_literals + +# from datetime import datetime + +from recommonmark.parser import CommonMarkParser + +# You should have received a copy of the GNU Affero General Public License +# along with this program. If not, see . +__author__ = 'Imran Iqbal' # noqa: E221 +__copyright__ = 'Copyright (C) 2019, MYII' # noqa: E221 +__license__ = 'Apache-2.0' # noqa: E221 +__version__ = 'latest' # noqa: E221 +__maintainer__ = 'Imran Iqbal' # noqa: E221 + + +# -- Project information ----------------------------------------------------- + +project = 'template-formula' +copyright = __copyright__.replace('Copyright (C) ', '') # noqa: A001 +author = __author__ +version = __version__ +release = __version__ + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['templates', '_templates', '.templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = ['.rst', '.md'] + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for the reStructuredText parser --------------------------------- + +file_insertion_enabled = False + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'template-formula' + + +# -- Options for Markdown output --------------------------------------------- + +source_parsers = { + '.md': CommonMarkParser, +} + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( + 'index', + 'template-formula.tex', + u'template-formula Documentation', + u'', + 'manual', + ), +] + + +# -- Functions: `setup`, docstring preprocessing, etc. ----------------------- + +def setup(app): + """Prepare the Sphinx application object. + + Used for providing a custom CSS file for override styles. + + Parameters + ---------- + app : object + The Sphinx application object. + + Returns + ------- + app : object + The Sphinx application object. + + """ + app.add_stylesheet('css/custom.css') + return app diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..a49c0c3 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. _index: + +.. ``template-formula`` documentation master file. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to template-formula's documentation! +============================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents + :numbered: + :glob: + + README + CONTRIBUTING + TOFS_pattern + AUTHORS + CHANGELOG diff --git a/pre-commit_semantic-release.sh b/pre-commit_semantic-release.sh new file mode 100755 index 0000000..9d34d74 --- /dev/null +++ b/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 .. diff --git a/release-rules.js b/release-rules.js new file mode 100644 index 0000000..c63c850 --- /dev/null +++ b/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'}, +]; diff --git a/release.config.js b/release.config.js new file mode 100644 index 0000000..afa0cb1 --- /dev/null +++ b/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 + }, + }, + }, +};