Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rhysd/changelog-from-release

Simple changelog generator from GitHub releases
https://github.com/rhysd/changelog-from-release

changelog generator github releases

Last synced: 13 days ago
JSON representation

Simple changelog generator from GitHub releases

Awesome Lists containing this project

README 

        
Generate Changelog from GitHub Releases

=======================================

[![CI][ci-badge]][ci]



`changelog-from-release` is a (too) small command line tool to generate changelog from

[GitHub Releases][gh-releases]. It fetches releases of the repository via GitHub API and generates

changelog in Markdown format. [References][gh-autolinks] like `#123` or `@rhysd` are automatically

linked.



For example, [CHANGELOG.md](./CHANGELOG.md) was generated from [the releases page][releases].



Other real-world examples:



- https://github.com/rhysd/actionlint/blob/main/CHANGELOG.md

- https://github.com/rhysd/hgrep/blob/main/CHANGELOG.md

- https://github.com/rhysd/git-brws/blob/master/CHANGELOG.md



## Installation



Download binary from [the releases page](https://github.com/rhysd/changelog-from-release/releases) or

build from sources with Go toolchain (1.22 or later).



```

$ go install github.com/rhysd/changelog-from-release/v3@latest

```



## Usage



Running `changelog-from-release` with no argument outputs a changelog text in Markdown format to

stdout. Please redirect the output to your changelog file.



```

$ cd /path/to/repo

$ changelog-from-release > CHANGELOG.md

$ cat CHANGELOG.md

```



For more command line usage, see the `-help` output.



Automation with [GitHub Actions][gh-actions] is also offered. Please read

[action's README](./action/README.md) for more details.



```yaml

- uses: rhysd/changelog-from-release/action@v3

  with:

    file: CHANGELOG.md

    github_token: ${{ secrets.GITHUB_TOKEN }}

```



## FAQ



### How to update changelog before adding the release tag?



For example, how to include changes for v1.2.3 in `CHANGELOG.md` before creating a Git tag `v1.2.3`?



Please use [a release draft][gh-draft].



1. Click 'Draft a new release' button in releases page and write up release note for the next release

2. Click 'Choose a tag' drop down and enter a tag name for the release which is not created yet. Then

   click '+ Create new tag: ... on publish' item in the drop down.

3. Save the draft by clicking 'Save draft'

4. Run `changelog-from-release` with setting [a personal access token][pat] to `$GITHUB_TOKEN`

   environment variable

5. Commit the generated changelog

6. Create and push the new Git tag. Ensure the tag name is the same as one entered at 2.

7. Go to the draft release page created at 1. and publish the release by clicking 'Publish release'

   button



Setting a personal access token at 2. is mandatory since release drafts are private information.

API token associated with your account is necessary to fetch it. If you use [the action](./action/README.md),

an API token is automatically generated by GitHub Actions so you don't need to create a token by

yourself.



### How to insert some templates at top/bottom of generated changelog?



Since `changelog-from-release` command just generates changelog history, you can insert your

favorite templates before/after redirecting the generated output to `CHANGELOG.md` file.



```sh

# Insert header

cat <<-EOS > CHANGELOG.md

Changelog

=========



This is a header.



EOS



changelog-from-release -l 2 >> CHANGELOG.md



# Insert footer

cat <<-EOS >> CHANGELOG.md



This is a footer.

EOS

```



If your shell supports `$()`, header and footer can be inserted once.



```sh

cat <<-EOS > CHANGELOG.md

Changelog

=========



This is a header.



$(changelog-from-release -l 2)



This is a footer.

EOS

```



`-l 2` means using `##` instead of `#` for each release section. Please adjust it for your use case.



If you're using [the action](./action/README.md), use `header` and `footer` inputs to insert texts

before/after the generated changelog.



```yaml

- uses: rhysd/changelog-from-release/action@v3

  with:

    file: CHANGELOG.md

    github_token: ${{ secrets.GITHUB_TOKEN }}

    args: -l 2

    header: |

      Changelog

      =========



      This is header.

    footer: |-



      This is footer.

```



### How to ignore some release tags?



For example, if your project has `nightly` tag release for nightly builds, it should be excluded from

changelog.



In this case, use `-i` command line option to ignore some release tags by regular expression:



```sh

changelog-from-release -i '^nightly$' > CHANGELOG.md

```



### How to extract some release tags?



For example, if your project uses `v{major}.{minor}.{patch}` format for release tags, a changelog

should be created with extracting them.



In this case, use `-e` command line option to extract some release tags by regular expression:



```sh

changelog-from-release -e '^v\d+\.\d+\.\d+$' > CHANGELOG.md

```



### How to ignore draft releases?



If you're using the GitHub Action and don't want draft releases to be included in the changelog, you

can use the `-d` flag to omit them:



```sh

changelog-from-release -d=false > CHANGELOG.md

```



## Reference auto linking



GitHub [automatically links][gh-autolinks] to references to resources.



`changelog-from-release` provides the same auto-linking feature. It automatically links the following

references and URLs in release notes.



### Issue reference



`#123` → `[#123](https://github.com/owner/repo/issues/123)`



External reference with `GH-` prefix is also supported.



`GH-123` → `[#123](https://github.com/owner/repo/issues/123)`



### User reference



`@rhysd` → `[@rhysd](https://github.com/rhysd)`



### Commit reference



`93e1af6ec49d23397baba466fba1e89cc8b6de39` → ``[`93e1af6ec4`](https://github.com/owner/repo/commit/93e1af6ec49d23397baba466fba1e89cc8b6de39)``



> [!Note]

> To avoid false-positives, only full-length (40 characters) commit hashes are converted.



### Custom autolink



`JIRA-123` → `[JIRA-123](https://jira.my-company.com/browse/PROJ-123)`



> [!Note]

> Custom autolinks are [configured][gh-config-autolink] on your repository. [The API to fetch the custom autolinks configuration][gh-api-autolink]

> requires "Administration" repository permissions (read). When the permission lacks, `changelog-from-release`

> ignores the custom autolinks. You need to set your personal access token to the `GITHUB_TOKEN` environment

> variable.



### Issue URL



`https://github.com/owner/repo/issues/123` → `[#123](https://github.com/owner/repo/issues/123)`



For outside repositories,



`https://github.com/other/repo/issues/123` → `[other/repo#123](https://github.com/owner/repo/issues/123)`



And URL to an issue comment is supported.



`https://github.com/owner/repo/issues/123#issue-1212591132` → `[#123 (comment)](https://github.com/owner/repo/issues/123#issue-1212591132)`



### Pull request URL



`https://github.com/owner/repo/pull/123` → `[#123](https://github.com/owner/repo/pull/123)`



For outside repositories,



`https://github.com/other/repo/pull/123` → `[other/repo#123](https://github.com/owner/repo/pull/123)`



And URL to a review comment is supported.



`https://github.com/owner/repo/pull/123#pullrequestreview-1212591132` → `[#123 (review)](https://github.com/owner/repo/pull/123#pullrequestreview-1212591132)`



### Commit URL



`https://github.com/owner/repo/commit/93e1af6ec4` → ``[`93e1af6ec4`](https://github.com/owner/repo/commit/93e1af6ec4)``



For outside repositories,



`https://github.com/other/repo/commit/93e1af6ec4` →  ``[other/repo`93e1af6ec4`](https://github.com/owner/repo/commit/93e1af6ec4)``



## Environment variables



### `GITHUB_API_BASE_URL`



For [GitHub Enterprise][ghe], please set `GITHUB_API_BASE_URL` environment variable to configure API

base URL.



```sh

export GITHUB_API_BASE_URL=https://github.your-company.com/api/v3/

```



### `GITHUB_TOKEN`



If `changelog-from-release` reported API rate limit exceeded or no permission to access the repository,

consider to specify [a personal access token][pat].



```sh

export GITHUB_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

```



## Bug report or feature request



Please [create an issue on GitHub][create-issue]. If something went wrong, it is helpful to include the debug log in the description. Debug log can be captured with the following command.



```sh

changelog-from-release -debug 2>log.txt

```



## License



[the MIT License](LICENSE.txt)



[gh-releases]: https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases

[releases]: https://github.com/rhysd/changelog-from-release/releases

[ci]: https://github.com/rhysd/changelog-from-release/actions/workflows/ci.yml

[ci-badge]: https://github.com/rhysd/changelog-from-release/actions/workflows/ci.yml/badge.svg

[gh-actions]: https://github.com/features/actions

[ghe]: https://github.com/enterprise

[pat]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

[gh-draft]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository

[gh-autolinks]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls

[gh-config-autolink]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources

[gh-api-autolink]: https://docs.github.com/en/rest/repos/autolinks

[create-issue]: https://github.com/rhysd/changelog-from-release/issues/new