diff --git a/README.md b/README.md
index eae74ab..7bd7e0c 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,182 @@ Specify the action as part of your GitHub actions workflow:
uses: mikepenz/release-changelog-builder-action@{latest-release}
```
+## Full Sample 🖥️
+
+Below is a complete example showcasing how to define a build, which is executed when tagging the project. It consists of:
+- Prepare tag, via the GITHUB_REF environment variable
+- Build changelog, given the tag
+- Create release on GitHub - specifying body with constructed changelog
+
+> [!NOTE]
+> Pre v4 PRs will only show up in the changelog if assigned one of the default label categories "feature", "fix" or "test". Starting with v4 these PRs will be in the `Uncategorized` section.
+
+Example
+
+
+```yml
+name: 'CI'
+on:
+ push:
+ tags:
+ - '*'
+
+jobs:
+ release:
+ if: startsWith(github.ref, 'refs/tags/')
+ runs-on: ubuntu-latest
+ steps:
+ - name: Build Changelog
+ id: github_release
+ uses: mikepenz/release-changelog-builder-action@v4
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Create Release
+ uses: mikepenz/action-gh-release@v0.2.0-a03 #softprops/action-gh-release
+ with:
+ body: ${{steps.github_release.outputs.changelog}}
+```
+
+
+Example w/ Configuration
+
+
+```yml
+jobs:
+ release:
+ if: startsWith(github.ref, 'refs/tags/')
+ runs-on: ubuntu-latest
+ steps:
+ - name: Build Changelog
+ uses: mikepenz/release-changelog-builder-action@v4
+ with:
+ configurationJson: |
+ {
+ "template": "#{{CHANGELOG}}\n\n\nUncategorized
\n\n#{{UNCATEGORIZED}}\n ",
+ "categories": [
+ {
+ "title": "## 💬 Other",
+ "labels": ["other"]
+ },
+ {
+ "title": "## 📦 Dependencies",
+ "labels": ["dependencies"]
+ }
+ ]
+ }
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+
+Example Commit Mode w/ Configuration
+
+
+```yml
+jobs:
+ release:
+ if: startsWith(github.ref, 'refs/tags/')
+ runs-on: ubuntu-latest
+ steps:
+ - name: Build Changelog
+ uses: mikepenz/release-changelog-builder-action@v4
+ with:
+ commitMode: true
+ configurationJson: |
+ {
+ "template": "#{{CHANGELOG}}",
+ "categories": [
+ {
+ "title": "## Feature",
+ "labels": ["feat", "feature"]
+ },
+ {
+ "title": "## Fix",
+ "labels": ["fix", "bug"]
+ },
+ {
+ "title": "## Other",
+ "labels": []
+ }
+ ],
+ "label_extractor": [
+ {
+ "pattern": "^(build|ci|chore|doc|docs|wiki|remove|deprecate|security|dependency|package|feat|feature|fix|bug|perf|optimize|refactor|revert|style|test):(.*)",
+ "target": "$1"
+ },
+ {
+ "pattern": "^(build|ci|chore|doc|docs|wiki|remove|deprecate|security|dependency|package|feat|feature|fix|bug|perf|optimize|refactor|revert|style|test){1}(\\([\\w\\-\\.]+\\))?(!)?:(.*)",
+ "target": "$1"
+ }
+ ],
+ }
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+This example defines a regex to extract the label from the commit message. Handling flags from the [Conventional Commit Standards](https://www.conventionalcommits.org/en/v1.0.0/).
+
+
+Example
-
-
-```yml
-name: 'CI'
-on:
- push:
- tags:
- - '*'
-
-jobs:
- release:
- if: startsWith(github.ref, 'refs/tags/')
- runs-on: ubuntu-latest
- steps:
- - name: Build Changelog
- id: github_release
- uses: mikepenz/release-changelog-builder-action@v3
- env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
- - name: Create Release
- uses: mikepenz/action-gh-release@v0.2.0-a03 #softprops/action-gh-release
- with:
- body: ${{steps.github_release.outputs.changelog}}
-```
-
-
-Example w/ Configuration
-
-
-```yml
-jobs:
- release:
- if: startsWith(github.ref, 'refs/tags/')
- runs-on: ubuntu-latest
- steps:
- - name: Build Changelog
- uses: mikepenz/release-changelog-builder-action@v3
- with:
- configurationJson: |
- {
- "template": "#{{CHANGELOG}}\n\n\nUncategorized
\n\n#{{UNCATEGORIZED}}\n ",
- "categories": [
- {
- "title": "## 💬 Other",
- "labels": ["other"]
- },
- {
- "title": "## 📦 Dependencies",
- "labels": ["dependencies"]
- }
- ]
- }
- env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-```
-
-
-Configuration in .yml
+
+
+```yml
+- name: Build Changelog
+ uses: mikepenz/release-changelog-builder-action@v4
+ with:
+ configurationJson: |
+ {
+ "template": "#{{CHANGELOG}}\n\n\nUncategorized
\n\n#{{UNCATEGORIZED}}\n ",
+ "categories": [
+ {
+ "title": "## 💬 Other",
+ "labels": ["other"]
+ }
+ ]
+ }
+```
+
+
+Configuration as json file
+
```yml
- name: "Build Changelog"
uses: mikepenz/release-changelog-builder-action@{latest-release}
with:
configuration: "configuration.json"
- env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
-> [!NOTE]
-> Defaults for the configuration can be found in the [configuration.ts](https://github.com/mikepenz/release-changelog-builder-action/blob/develop/src/configuration.ts)
-
> [!WARNING]
> It is required to have a `checkout` step prior to the changelog step if `configuration` is used, to allow the action to discover the configuration file. Use `configurationJson` as alternative.
+
+Example regex configuration block
+
-PR title input
+Sample extracts a ticket number from the title
+
+Sample PR title input
```
[XYZ-1234] This is my PR title
```
Regex replace pattern
+
```
{
"name": "TICKET",
@@ -523,7 +614,9 @@ Regex replace pattern
}
```
-Regex replace pattern
+Regexr style pattern (Use [regexr.com](https://regexr.com/) to test).
+To test on regexr inverse the escaping of `\\` to `\`
+
```
{
"name": "TICKET",
@@ -536,6 +629,9 @@ Regex replace pattern
}
```
+
+