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

@@ -8,28 +8,27 @@
 The purpose of this action is to enforce a change to a ongoing changelog file. Inspired by [Keep A Changelog](https://keepachangelog.com/en/1.0.0/), this action helps development teams to keep a change file up to date as new features or fixes are implemented. 
 
 ### 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.
+To use, follow the typical GitHub Action `uses` syntax. An example workflow using the default parameters of this action is shown below:
 
 ```yaml
 name: "Pull Request Workflow"
 on:
   pull_request:
-      types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
+    # The specific activity types are listed here to include "labeled" and "unlabeled" since the enforcer allows for skipping enforcement of the changelog being edited via the "skipLabels" property
+    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:
+    # The checkout step is required since this action uses local git commands to enforce the changelog
     - uses: actions/checkout@v2
     - uses: dangoslen/changelog-enforcer@v2
-      with:
-        changeLogPath: 'CHANGELOG.md'
-        skipLabels: 'Skip-Changelog'
 ```
 
+Other examples can be seen in the [example-workflows](./example-workflows) directory in this repository.
+
 _: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)._
 
 ### Inputs / Properties
@@ -41,7 +40,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 +57,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 (`\`) 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 (`\`) 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

example-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'
+```

example-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 }}
+```

example-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 }}
+```