Merge pull request #183 from dafyddj/add-README

Improve reusability

Author: myii

.rubocop.yml

@@ -8,5 +8,7 @@ Metrics/LineLength:
   Max: 88
 
 # Any offenses that should be fixed, e.g. collected via. `rubocop --auto-gen-config`
+# <REMOVEME
 Metrics/BlockLength:
   Max: 36
+# REMOVEME>

.travis.yml

@@ -100,6 +100,7 @@ jobs:
     # - env: INSTANCE=default-amazonlinux-2-2017-7-py2
     # - env: INSTANCE=default-arch-base-latest-2017-7-py2
 
+    # <REMOVEME
     # Test the conversion of `template-formula` into another formula
     # ready for development
     - env: 'Conversion'
@@ -110,7 +111,7 @@ jobs:
         - DEBUG=true bin/convert-formula.sh converted
         - '[ $(git rev-list HEAD --count) -eq 2 ]'
         - bin/kitchen verify default-debian-10-2019-2-py3
-
+    # REMOVEME>
     ## Define the release stage that runs `semantic-release`
     - stage: 'release'
       language: 'node_js'

bin/convert-formula.sh

@@ -43,6 +43,12 @@ convert_formula() {
   git mv TEMPLATE "${NEW_NAME}"
   grep --recursive --files-with-matches --exclude-dir=.git TEMPLATE . \
     | xargs -L 1 ex -u NONE -sc '%s/TEMPLATE/'"${NEW_NAME}"'/g|x'
+  # Searching across multiple lines.
+  # See https://vim.fandom.com/wiki/Search_across_multiple_lines
+  ex -u NONE -sc '%s/^.. <REMOVEME\_.\{-}.. REMOVEME>/None/g|x' docs/README.rst
+  ex -u NONE -sc '%s/^\s*# <REMOVEME\_.\{-}# REMOVEME>\n//g|x' .travis.yml
+  ex -u NONE -sc '%s/^\s*# <REMOVEME\_.\{-}# REMOVEME>\n//g|x' .rubocop.yml
+  ex -u NONE -sc '%s/^\(version:\).*/\1 1.0.0/g|x' FORMULA
   # shellcheck disable=SC2016 # Expressions don't expand in single quotes
   git commit --quiet --all \
     --message 'feat: convert `template-formula` to `'"${NEW_NAME}"'-formula`' \

docs/README.rst

@@ -45,7 +45,33 @@ Please see `How to contribute <https://github.com/saltstack-formulas/.github/blo
 Special notes
 -------------
 
-None
+.. <REMOVEME
+
+Using this template
+^^^^^^^^^^^^^^^^^^^
+
+The easiest way to use this template formula as a base for a new formula is to use GitHub's **Use this template** button to create a new repository. For consistency with the rest of the formula ecosystem, name your formula repository following the pattern ``<formula theme>-formula``, where ``<formula theme>`` consists of lower-case alphabetic characters and numbers.
+
+In the rest of this example we'll use ``example`` as the ``<formula theme>``.
+
+Follow these steps to complete the conversion from ``template-formula`` to ``example-formula``. ::
+
+  $ git clone [email protected]:YOUR-USERNAME/example-formula.git
+  $ cd example-formula/
+  $ bin/convert-formula.sh example
+  $ git push --force
+
+Alternatively, it's possible to clone ``template-formula`` into a new repository and perform the conversion there. For example::
+
+  $ git clone https://github.com/saltstack-formulas/template-formula example-formula
+  $ cd example-formula/
+  $ bin/convert-formula.sh example
+
+To take advantage of `semantic-release <https://github.com/semantic-release/semantic-release>`_ for automated changelog generation and release tagging, you will need a GitHub `Personal Access Token <https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line>`_ with at least the **public_repo** scope.
+
+In the Travis repository settings for your new repository, create an `environment variable <https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings>`_ named ``GH_TOKEN`` with the personal access token as value, restricted to the ``master`` branch for security.
+
+.. REMOVEME>
 
 Available states
 ----------------