Merge pull request #6 from sarnold/examples

document an example repo

.github/workflows/main.yml

@@ -9,7 +9,17 @@ on:
 
 jobs:
   gitchangelog_test:
-    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-18.04, ubuntu-20.04]
+
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+
     name: Test changelog
     steps:
       # To use this repository's private action,
@@ -19,6 +29,13 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Get version
+        if: matrix.os == 'ubuntu-20.04'
+        id: get_version
+        run: |
+          echo "VERSION=$(git describe --abbrev=0 --tags)" >> $GITHUB_ENV
+          echo ${{ env.VERSION }}
+
       - name: gitchangelog action step (debug)
         uses: ./ # Uses an action in the root directory
         with:
@@ -27,6 +44,16 @@ jobs:
       - name: Display changes file
         run: cat CHANGES.md
 
+      - name: Test changes file
+        run: |
+          export VERSION=${{ env.VERSION }}
+          export TITLE_VERSION=$(cat CHANGES.md | head -n1 | cut -f2 -d" ")
+          if [[ -n $VERSION ]]; then
+            [[ "${TITLE_VERSION}" == "${VERSION}" ]] || exit 1
+          else
+            [[ "${TITLE_VERSION}" == "(unreleased)" ]] || exit 1
+          fi
+
       - name: Checkout test repo
         uses: actions/checkout@v2
         with:

README.rst

@@ -41,11 +41,23 @@ is shown below.
 .. _MarkDown: https://www.markdownguide.org/
 .. _softprops/action-gh-release: https://github.com/softprops/action-gh-release
 
+Examples
+========
+
+The canonical dogfood_ example is the `release.yml`_ and corresponding
+`github release page`_ in the gitchangelog repo (for a non-platform wheel).
+
+
+.. _dogfood: http://catb.org/jargon/html/D/dogfood.html
+.. _release.yml: https://github.com/sarnold/gitchangelog/blob/master/.github/workflows/release.yml#L58
+.. _github release page: https://github.com/sarnold/gitchangelog/releases/tag/3.0.7
+
 
 Usage
 =====
 
-Create a .yml file under .github/workflows with the following contents.
+To enable the default release page changes file, create a .yml file under
+.github/workflows with the following contents.
 
 Default configuration
 ---------------------
@@ -70,6 +82,12 @@ Default configuration
               github_token: ${{ secrets.GITHUB_TOKEN}}
 
 
+The above is enough to generate the default release output, but should
+be paired with a release action to populate the github release page (as
+shown below).  The action will try its best to figure out the current
+and previous tags, however, if you set the VERSION variable it will be
+used for the current tag in the change diff.
+
 Full configuration
 ------------------