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

Merge pull request #22 from mikepenz/feature/improve_readme

Browse Source 
Improve README
This commit is contained in:
Mike Penz
2020-10-17 10:40:03 +02:00
committed by GitHub
parent f1d1eb5aea 876d5042a3
commit 5ce9cb0351
1 changed files with 79 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+79 -35
View File
@@ -1,11 +1,51 @@
<div align="center">
:octocat:
</div>
<h1 align="center">
release-changelog-builder-action
</h1>
# release-changelog-builder-action
<p align="center">
... a github action that builds your release notes, fast, easy and exactly the way you want.
</p>
Builds the release notes between two tags (or refs) from pull requests merged.
<div align="center">
<a href="https://github.com/mikepenz/release-changelog-builder-action/actions">
<img src="https://github.com/mikepenz/release-changelog-builder-action/workflows/CI/badge.svg"/>
</a>
</div>
<br />
## Action usage
-------
Include this action in your build by defining the action in your workflow:
<p align="center">
<a href="#whats-included-">What's included 🚀</a> &bull;
<a href="#setup">Setup 🛠️</a> &bull;
<a href="#customization-%EF%B8%8F">Customization 🖍️</a> &bull;
<a href="#contribute-">Contribute 🧬</a> &bull;
<a href="#license">License 📓</a> &bull;
</p>
-------
### What's included 🚀
- Super simple integration
- even on huge repositories with hundreds of tags
- Parallel releases support
- Blazing fast execution
- Suports any git project
- Highly flexible configuration
- Lightweight
- Supports any branch
-------
## Setup
### Configure the workflow
Specify the action as part of your GitHub actions workflow:
```yml
- name: "Build Changelog"
@@ -16,17 +56,20 @@ Include this action in your build by defining the action in your workflow:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
This will automatically pull the tag from the current commit (the latest tag), and try to resolve the tag before this.
By default the action will try to automatically retrieve the `tag` from the current commit, and automtacally resolve the `tag` before. Read more about this here.
## Action outputs
### Action outputs
The result of this action is returned via the outputs, and can be retrieved via the `changelog` value in the step afterwards. See the `test.yml` for a sample.
The action will succeed and return the `changelog` as a step output. Use it in any follow up step, by referencing via its id. For example `build_changelog`.
```yml
# ${{steps.{CHANGELOG_STEP_ID}.outputs.changelog}}
${{steps.build_changelog.outputs.changelog}}
```
## Configuration
## Customization 🖍️
### Changelog Configuration
By default the action will look for a file called `configuration.json` within the root of the repository to load the config from. If this file does not exist, defaults are used.
@@ -37,10 +80,6 @@ By default the action will look for a file called `configuration.json` within th
"title": "## 🚀 Features",
"labels": ["feature"]
},
{
"title": "## 🦄 Internal Features",
"labels": ["internal"]
},
{
"title": "## 🐛 Fixes",
"labels": ["fix"]
@@ -73,7 +112,7 @@ Any section of the configruation 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)
## Advanced workflow specification
### Advanced workflow specification
For advanced usecases additional settings can be provided to the action
@@ -86,32 +125,38 @@ For advanced usecases additional settings can be provided to the action
configuration: "configuration_complex.json"
owner: "mikepenz"
repo: "release-changelog-builder-action"
ignorePreReleases: "false" # allows to skip any pre releases, if `fromTag` needs to be automatically resolved (ignores 0.0.2-rc02 for example) - only relevant if `fromTag` is not provided
ignorePreReleases: "false"
fromTag: "0.0.2"
toTag: "0.0.3"
token: ${{ secrets.GITHUB_TOKEN }} # the token to use, for a different repository a PAT is required (Personal access token)
token: ${{ secrets.PAT }}
```
## PR Template placeholders
💡 `ignorePreReleases` will be ignored, if `fromTag` is specified. `${{ secrets.GITHUB_TOKEN }}` only grants rights to the current repository, for other repos please use a PAT.
| Variable | Description |
| --------- | -------------------------- |
| `${{NUMBER}}` | Pull request number |
| `${{TITLE}}` | The title of the pull request |
| `${{URL}}` | The URL linking to the pull request |
| `${{MERGED_AT}}` | The time this PR was merged |
| `${{AUTHOR}}` | The author of the pull request |
| `${{BODY}}` | The body / description of the pull request |
### PR Template placeholders
## Template placeholdrs
Table of supported placeholders allowed to be used in the `template` configuration.
| Variable | Description |
| --------- | -------------------------- |
| `${{CHANGELOG}}` | The contents of the main changelog, matching the labels as specified in the categories configuration |
| `${{UNCATEGORIZED}}` | All pull requests not matching a label |
| **Placeholder** | **Description** |
|------------------|-------------------------------------------------------------|
| `${{NUMBER}}` | The number referencing this pull request. E.g. 13 |
| `${{TITLE}}` | Specified title of the merged pull request |
| `${{URL}}` | Url linking to the pull request on GitHub |
| `${{MERGED_AT}}` | The ISO time, the pull request was merged at |
| `${{AUTHOR}}` | Author creating and opening the pull request |
| `${{BODY}}` | Description/Body of the pull request as specified on GitHub |
### Template placeholders
Table of supported placeholders allowed to be used in the `pr_template` configuration.
| **Placeholder** | **Description** |
|----------------------|-------------------------------------------------------------------------------------------------|
| `${{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 |
# Contribute
## Contribute 🧬
```bash
# Install the dependencies
@@ -133,23 +178,22 @@ It's suggested to export the token to your path, before running the tests, so AP
export GITHUB_TOKEN=your_personal_github_pat
```
# Developed By
## Developed By
* Mike Penz
* [mikepenz.com](http://mikepenz.com) - <mikepenz@gmail.com>
* [paypal.me/mikepenz](http://paypal.me/mikepenz)
# Credits
## Credits
Core parts of the PR fetching logic, are based on [pull-release-notes](https://github.com/nblagoev/pull-release-notes)
- Nikolay Blagoev - [GitHub](https://github.com/nblagoev/)
# License
## License
Copyright for portions of pr-release-notes are held by Nikolay Blagoev, 2019-2020 as part of project pull-release-notes. All other copyright for project pr-release-notes are held by Mike Penz, 2020.
# Fork License
## Fork License
All patches and changes applied to the original source are licensed under the Apache 2.0 license.