mikepenz/release-changelog-builder-action
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #38 from mikepenz/feature/further_enhance_documentation

Browse Source 
Improve documentation
This commit is contained in:
Mike Penz
2020-10-18 11:43:58 +02:00
committed by GitHub
parent 2f5aa9600c e1cd50cb75
commit baf0b87ba2
1 changed files with 63 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+63 -39
View File
@@ -21,9 +21,9 @@
<p align="center"> <p align="center">
<a href="#whats-included-">What's included 🚀</a> &bull; <a href="#whats-included-">What's included 🚀</a> &bull;
<a href="#setup">Setup 🛠️</a> &bull; <a href="#setup">Setup 🛠️</a> &bull;
<a href="#full-sample-%EF%B8%8F">Full Sample 🖥️</a> &bull;
<a href="#customization-%EF%B8%8F">Customization 🖍️</a> &bull; <a href="#customization-%EF%B8%8F">Customization 🖍️</a> &bull;
<a href="#contribute-">Contribute 🧬</a> &bull; <a href="#contribute-">Contribute 🧬</a> &bull;
<a href="#complete-sample-%EF%B8%8F">Complete Sample 🖥️</a> &bull;
<a href="#license">License 📓</a> <a href="#license">License 📓</a>
</p> </p>
@@ -79,9 +79,45 @@ A full set list of possible output values for this action.
| `outputs.toTag` | Defines the `toTag` which describes the upper bound to process pull request for | | `outputs.toTag` | Defines the `toTag` which describes the upper bound to process pull request for |
| `outputs.failed` | Defines if there was an issue with the action run, and the changelog may not have been generated correctly. [true, false] | | `outputs.failed` | Defines if there was an issue with the action run, and the changelog may not have been generated correctly. [true, false] |
## 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
```yml
name: 'CI'
on:
push:
tags:
- '*'
release:
if: startsWith(github.ref, 'refs/tags/')
runs-on: ubuntu-latest
steps:
- name: Build Changelog
id: github_release
uses: mikepenz/release-changelog-builder-action@main
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Create Release
uses: actions/create-release@v1
with:
tag_name: ${{ github.ref }}
release_name: ${{ github.ref }}
body: ${{steps.github_release.outputs.changelog}}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
## Customization 🖍️ ## Customization 🖍️
### Changelog Configuration ### Configuration
The action supports flexible configuration options to modify vast areas of its behavior. To do so, provide the configuration file to the workflow using the `configuration` setting. The action supports flexible configuration options to modify vast areas of its behavior. To do so, provide the configuration file to the workflow using the `configuration` setting.
@@ -131,9 +167,11 @@ This configuration is a `.json` file in the following format.
} }
``` ```
Any section of the configruation can be ommited to have defaults apply. Any section of the configuration can be ommited to have defaults apply.
Defaults for the configuraiton can be found in the [configuration.ts](https://github.com/mikepenz/release-changelog-builder-action/blob/develop/src/configuration.ts)
Defaults for the configuration can be found in the [configuration.ts](https://github.com/mikepenz/release-changelog-builder-action/blob/develop/src/configuration.ts)
Please see the [Configuration Specification](#configuration-specification) for detailed descriptions on the offered configuration options.
### Advanced workflow specification ### Advanced workflow specification
@@ -149,12 +187,12 @@ For advanced usecases additional settings can be provided to the action
owner: "mikepenz" owner: "mikepenz"
repo: "release-changelog-builder-action" repo: "release-changelog-builder-action"
ignorePreReleases: "false" ignorePreReleases: "false"
fromTag: "0.0.2" fromTag: "0.3.0"
toTag: "0.0.3" toTag: "0.5.0"
token: ${{ secrets.PAT }} token: ${{ secrets.PAT }}
``` ```
💡 All input values are optional. It is only required to privde the `token` either via the input, or as `env` variable. 💡 All input values are optional. It is only required to provide the `token` either via the input, or as `env` variable.
| **Input** | **Description** | | **Input** | **Description** |
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -196,40 +234,26 @@ Table of supported placeholders allowed to be used in the `pr_template` configur
| `${{CHANGELOG}}` | The contents of the changelog, matching the labels as specified in the categories configuration | | `${{CHANGELOG}}` | The contents of the changelog, matching the labels as specified in the categories configuration |
| `${{UNCATEGORIZED}}` | All pull requests not matching a specified label in categories | | `${{UNCATEGORIZED}}` | All pull requests not matching a specified label in categories |
### Configuration Specification
## Complete Sample 🖥️ Table of descriptions for the `configuration.json` options.
Below is a complete example showcasing how to define a build, which is executed when tagging the project. It consists of: | **Input** | **Description** |
- Prepare tag, via the GITHUB_REF environment variable |--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
- Build changelog, given the tag | categories | An array of `category` specifications, offering a flexible way to group changes into categories |
- Create release on GitHub - specifying body with constructed changelog | category.title | The display name of a category in the changelog |
| category.labels | An array of labels, to match pull request label against. If any PR label, matches any category label, the pull request will show up under this category |
```yml | sort | The sort order of pull requests. [ASC, DESC] |
name: 'CI' | template | Specifies the global template to pick for creating the changelog. See [Template placeholders](#template-placeholders) for possible values |
on: | pr_template | Defines the per pull request template. See [PR Template placeholders](#pr-template-placeholders) for possible values |
push: | empty_template | Template to pick if no changes are detected. Does not support placeholders |
tags: | transformers | An array of `transform` specification, offering a flexible API to modify the text per pull request. This is applied on the change text created with `pr_template`. `transformers` are executed per change, in the order specified |
- '*' | transformer.pattern | A `regex` pattern, extracting values of the change message. |
| transformer.target | The result pattern, the regex groups will be filled into. Allows for full transformation of a pull request message. Including potentially specified texts |
release: | max_tags_to_fetch | The maximum amount of tags to load from the API to find the previous tag. Loaded paginated with 100 per page |
if: startsWith(github.ref, 'refs/tags/') | max_pull_requests | The maximum amount of pull requests to load from the API. Loaded paginated with 30 per page |
runs-on: ubuntu-latest | max_back_track_time_days | Defines the max amount of days to go back in time per changelog |
steps: | exclude_merge_branches | An array of branches to be ignored from processing as merge commits |
- name: Build Changelog
id: github_release
uses: mikepenz/release-changelog-builder-action@main
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Create Release
uses: actions/create-release@v1
with:
tag_name: ${{ github.ref }}
release_name: ${{ github.ref }}
body: ${{steps.github_release.outputs.changelog}}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
## Contribute 🧬 ## Contribute 🧬