Improving documentation based on feedback

.github/workflows/pull_request.yml

@@ -33,7 +33,6 @@ jobs:
         with:
           commit_message: "Auto-package action"
 
-
   # test action works running from the graph
   enforce-changelog:
     runs-on: ubuntu-latest

README.md

@@ -10,7 +10,7 @@ The purpose of this action is to enforce a change to a ongoing changelog file. I
 ### Usage
 To use, follow the typical GitHub Action `uses` syntax. 
 
-Requires the common [Checkout Action](https://github.com/marketplace/actions/checkout) as shown below. The enforcement of change is done all using local `git` commands and requires the repository be checked out.
+Requires the common [Checkout Action](https://github.com/marketplace/actions/checkout) as shown below. The enforcement of change is done all using local `git` commands and requires the repository be checked out. You can also view [other workflow examples](./example-workflows/) that uses various properties of this action.
 
 ```yaml
 name: "Pull Request Workflow"
@@ -25,9 +25,6 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - uses: dangoslen/changelog-enforcer@v2
-      with:
-        changeLogPath: 'CHANGELOG.md'
-        skipLabels: 'Skip-Changelog'
 ```
 
 _:warning: The Changelog Enforcer is designed to be used with the `pull_request` or `pull_request_target` event types. Using this action on any other event type will result in a warning logged and the action succeeding (as to not block the rest of a workflow)._
@@ -41,7 +38,7 @@ Below are the properties allowed by the Changelog Enforcer. These properties are
 
 #### `skipLabels` 
 * Default: `'Skip-Changelog'` 
-* List of labels used to skip enforcing of the changelog during a pull request. Each label name is comma separated and only one label needs to be present for enforcement to be skipped. 
+* List of labels used to skip enforcing of the changelog during a pull request. Each label name is comma separated and only one label needs to be present for enforcement to be skipped.
 
   For example, if `label-1,label-2` was supplied as the `skipLabels`, `label-1` _or_ `label-2` would skip the enforcer. Each label is trimmed for leading and trailing spaces since GitHub labels do not allow for leading or trailing spaces. Thus, the following lists are equivalent:
   * `label-1,label-2`
@@ -58,7 +55,11 @@ Below are the properties allowed by the Changelog Enforcer. These properties are
 
 #### `versionPattern`
 * Default: `'## \\[((v|V)?\\d*\\.\\d*\\.\\d*-?\\w*|unreleased|Unreleased|UNRELEASED)\\]'`
-* A regex pattern used to extract the versions from the changelog. Changelog Enforcer assumes the use of the KeepAChangelog.com convention, and as such looks for a line starting with `## [version] - date`. Your regex should match the version as the 2nd match group. The regex pattern is used with global and multiline flags. Also note that since this is passed as a String, you will need to escape a backslash `\` character via `\\`
+* A regex pattern used to extract the version section headings from the changelog. Changelog Enforcer assumes the use of the [KeepAChangelog.com](https://keepachangelog.com/en/1.0.0/) convention for section headings, and as such looks for a line starting with `## [version] - date`. Versions are only extracted from the changelog when enforcing the expected latest version (via the `expectedLatestVersion` property).
+
+  If you supply your own regex to match a different format, your regex must match the version string as a capture group (in the default format, that's the part inside square brackets). The first capture group will be used if your regex includes multiple groups. The regex pattern is used with global and multiline flags to find all of the versions in the changelog.
+
+  Because the regex is passed as a `String` object, you will need to escape backslash characters (`\`) character via `\\`.
 
 ### Outputs
 

action.yml

@@ -28,15 +28,13 @@ inputs:
     default: ''
   versionPattern:
     description: |
-      "A regex pattern used to extract the versions from the changelog. Changelog Enforcer assumes the use of the KeepAChangelog.com convention, and 
-      as such looks for a line starting with '## [version] - date. Your regex should match the version as the 2nd match group.
-      The regex pattern is used with global and multiline flags. Also note that since this
-      is passed as a String, you will need to escape a backslash \ character via \\"
+      "A regex pattern used to extract the version section headings from the changelog. Changelog Enforcer assumes the use of the [KeepAChangelog.com](https://keepachangelog.com/en/1.0.0/) convention for section headings, and as such looks for a line starting with `## [version] - date`. Versions are only extracted from the changelog when enforcing the expected latest version (via the `expectedLatestVersion` property).
+
+      If you supply your own regex to match a different format, your regex must match the version string as a capture group (in the default format, that's the part inside square brackets). The first capture group will be used if your regex includes multiple groups. The regex pattern is used with global and multiline flags to find all of the versions in the changelog.
+
+      Because the regex is passed as a `String` object, you will need to escape backslash characters (`\`) character via `\\`."
     required: true
     default: "^## \\[((v|V)?\\d*\\.\\d*\\.\\d*-?\\w*|unreleased|Unreleased|UNRELEASED)\\]"
-    deprecatedMessage: |
-      "This input has been deprecated as of `v2.1.0`. In a future release - likely `v3.0.0`, the ChangeLog Enforcer will only support KeepAChangelog.com format 
-      for finding the latst expected version"
   missingUpdateErrorMessage:
     description: "The error message logged and returned in the 'errorMessage' output when no update to the changelog has been found."
     required: false

examples-workflows/with-different-changelog-path.yaml

@@ -0,0 +1,16 @@
+```yaml
+name: "Different Changelog Path"
+on:
+  pull_request:
+      types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
+
+jobs:
+  # Enforces the update of a changelog file on every pull request 
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: dangoslen/changelog-enforcer@v2
+      with:
+        changeLogPath: 'different/changelog.md'
+```

examples-workflows/with-expected-latest-version-custom-pattern.yaml

@@ -0,0 +1,25 @@
+```yaml
+name: "Checking for Expected Latest Version and Custom Version Pattern"
+on:
+  pull_request:
+      types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
+
+jobs:
+  # Enforces the update of a changelog file on every pull request 
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2.3.4
+
+      - id: read-version
+        run: |
+          echo "::set-output name=version::$(jq -r ".version" package.json)"
+
+      - id: changelog-enforcer
+        uses: ./
+        with:
+          skipLabels: "skip-changelog"
+          # Anything within the brackets that starts with *
+          versionPattern: " ^\\* \\[(.*)\\]"
+          expectedLatestVersion: ${{ steps.read-version.outputs.tag }}
+```

examples-workflows/with-expected-latest-version.yaml

@@ -0,0 +1,23 @@
+```yaml
+name: "Checking for Expected Latest Version"
+on:
+  pull_request:
+      types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
+
+jobs:
+  # Enforces the update of a changelog file on every pull request 
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2.3.4
+
+      - id: read-version
+        run: |
+          echo "::set-output name=version::$(jq -r ".version" package.json)"
+
+      - id: changelog-enforcer
+        uses: ./
+        with:
+          skipLabels: "skip-changelog"
+          expectedLatestVersion: ${{ steps.read-version.outputs.tag }}
+```