Skip to content
This repository has been archived by the owner on Oct 10, 2021. It is now read-only.

docs: update README #29

Merged
merged 2 commits into from
Apr 4, 2021
Merged

docs: update README #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0903168
docs: update README
ScottBrenner Apr 4, 2021
27dbf57
MD034/no-bare-urls Bare URL used
ScottBrenner Apr 4, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 29 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,81 +2,47 @@

GitHub Action for [lob/generate-changelog](https://github.com/lob/generate-changelog/). Intended to be used with [actions/create-release](https://github.com/actions/create-release).

**Note:** [Your repository must contain a `package.json` file.](https://github.com/lob/generate-changelog/issues/38#issuecomment-362726723)

Created during the GitHub Actions Hackathon 2020 and [selected as one of the winning projects!](https://docs.google.com/spreadsheets/d/1YL6mjJXGt3-75GejQCubsOvWwtYcGaqbJA7msnsh7Tg/edit#gid=0&range=A100:C100)

## Example workflow - create a release
Extends [actions/create-release: Example workflow - create a release](https://github.com/actions/create-release#example-workflow---create-a-release) to generate changelog from git commits and use it as the body for the GitHub release.
## Usage

```yaml
on:
push:
# Sequence of patterns matched against refs/tags
tags:
- 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
**Note:** [Your repository must contain a `package.json` file](https://github.com/lob/generate-changelog/issues/38#issuecomment-362726723), although an empty file such as [the one in this repository](https://github.com/ScottBrenner/generate-changelog-action/blob/master/package.json) is fine.

name: Create Release
If your `package.json` isn't available in root directory of your repository, you can pass the path of the `package.json` file by setting `package-dir` as follows:

jobs:
build:
name: Create Release
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Changelog
uses: scottbrenner/generate-changelog-action@master
id: Changelog
- name: Create Release
id: create_release
uses: actions/create-release@latest
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token
with:
tag_name: ${{ github.ref }}
release_name: Release ${{ github.ref }}
body: |
${{ steps.Changelog.outputs.changelog }}
draft: false
prerelease: false
```yaml
- name: Changelog
uses: scottbrenner/generate-changelog-action@master
id: Changelog
with:
package-dir: 'root/to/my/package.json'
```

The above workflow will create a release that looks like:
![Release](release.png)

If your `package.json` isn't available in root, you can pass the directory of the `package.json`:
By default, this Action generates changelogs using commits between the previous tag and the most recent tag. Generate changelogs from specific tag or range (e.g. `v1.2.3` or `v1.2.3..v1.2.4`) by passing the `from-tag` and `to-tag` inputs. An example is when your release tag on git is generated after the changelog so you must use something like `git log v1..HEAD --oneline`:

```yaml
- name: Changelog
uses: scottbrenner/generate-changelog-action@master
id: Changelog
with:
package-dir: 'root/to/my/package.json'
- name: Changelog
uses: scottbrenner/generate-changelog-action@master
id: Changelog
with:
from-tag: v1.0
to-tag: HEAD
```

If your use case does not need to generate changelog from latest and latest-1 tags, you can pass the custom flags. An example is when your release tag on git is generated after the changelog so you must use something like _git log v1..HEAD_ --oneline:
This Action additionally supports the following inputs, in accordance with [lob/generate-changelog's CLI options](https://github.com/lob/generate-changelog/#cli).
| Property | Default | Description |
| ------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `package-dir` | `package.json`| The path for the package.json if it is not in root |
| `from-tag` | "last tag" | The tag to generate changelog from. If not set, fallbacks to git last tag -1. Ex.: v1.0 |
| `to-tag` | "current tag" | The tag to generate changelog up to. If not set, fallbacks to git last tag. Ex.: v2.0 |
| `type` | Unset | The type of changelog to generate: patch, minor, or major. If not set, fallbacks to unset. |
| `exclude` | Unset | Exclude selected commit types (comma separated). If not set, fallbacks to unset. |
| `allow-unknown` | Unset | Allow unknown commit types. If not set, fallbacks to unset.

```yaml
- name: Changelog
uses: scottbrenner/generate-changelog-action@master
id: Changelog
with:
package-dir: 'root/to/my/package.json'
from-tag: v1.0
to-tag: HEAD
```
For more information, see [actions/create-release: Usage](https://github.com/actions/create-release#usage), [lob/generate-changelog: Usage](https://github.com/lob/generate-changelog#usage), and [jobs.<job_id>.steps[*].with](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepswith).

For more information, see [actions/create-release: Usage](https://github.com/actions/create-release#usage) and [lob/generate-changelog: Usage](https://github.com/lob/generate-changelog#usage)

## Example workflow - create a release
See [this repository's release.yml](https://github.com/ScottBrenner/generate-changelog-action/blob/master/.github/workflows/release.yml) for an example workflow which extends [actions/create-release: Example workflow - create a release](https://github.com/actions/create-release#example-workflow---create-a-release) to generate a changelog from git commits and use it as the body for the GitHub release.

| Property | Default | Description |
| ------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| package-dir | package.json | The path for the package.json if it is not in root |
| from-tag | "last tag" | The tag to generate changelog from. If not set, fallbacks to git last tag -1. Ex.: v1.0 |
| to-tag | "current tag" | The tag to generate changelog up to. If not set, fallbacks to git last tag. Ex.: v2.0 |
| type | Unset | The type of changelog to generate: patch, minor, or major. If not set, fallbacks to unset. |
| exclude | Unset | Exclude selected commit types (comma separated). If not set, fallbacks to unset. |
| allow-unknown | Unset | Allow unknown commit types. If not set, fallbacks to unset. |
This workflow automatically creates [this repository's releases](https://github.com/ScottBrenner/generate-changelog-action/releases).
Binary file removed release.png
View file
Open in desktop
Binary file not shown.